@ludecker/aaac 1.1.5 → 1.2.0

package/templates/cursor/aaac/scripts/remediation/fallow-scan.mjs

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+/**
+ * Run full Fallow scan suite for remediation campaigns:
+ *   dead-code, dupes, health (whole-repo JS/TS via frontend root).
+ *
+ * Usage:
+ *   node fallow-scan.mjs --campaign-id <id> --iteration <n> [--save-baseline]
+ */
+import fs from "fs";
+import path from "path";
+import { spawnSync } from "child_process";
+import { fileURLToPath } from "url";
+import { REPO_ROOT, isoNow, readJson, writeJson } from "../run-engine/lib.mjs";
+import {
+  FRONTEND_ROOT,
+  runFallow,
+  summarizeDeadCode,
+  summarizeDupes,
+  summarizeHealth,
+} from "./lib/fallow-metrics.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CAMPAIGNS_ROOT = path.join(REPO_ROOT, ".cursor/aaac/state/campaigns");
+
+const SCAN_TARGETS = [
+  {
+    id: "dead-code",
+    subcommand: "dead-code",
+    extraArgs: [],
+    outFile: "fallow-scan.json",
+    summarize: summarizeDeadCode,
+    baselineFile: "fallow-start-baseline.json",
+    baselineField: "fallow_total_issues",
+    iterBaselineField: "fallow_total_issues",
+  },
+  {
+    id: "dupes",
+    subcommand: "dupes",
+    extraArgs: [],
+    outFile: "fallow-dupes.json",
+    summarize: summarizeDupes,
+    baselineFile: "fallow-start-dupes-baseline.json",
+    baselineField: "clone_groups",
+    iterBaselineField: "fallow_dupes_clone_groups",
+  },
+  {
+    id: "health",
+    subcommand: "health",
+    extraArgs: ["--score", "--hotspots", "--top", "20"],
+    outFile: "fallow-health.json",
+    summarize: summarizeHealth,
+    baselineFile: "fallow-start-health-baseline.json",
+    baselineField: "health_score",
+    iterBaselineField: "fallow_health_score",
+  },
+];
+
+function parseArgs(argv) {
+  const out = { campaignId: null, iteration: 0, saveBaseline: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--campaign-id") out.campaignId = argv[++i];
+    else if (a === "--iteration") out.iteration = Number(argv[++i]);
+    else if (a === "--save-baseline") out.saveBaseline = true;
+  }
+  return out;
+}
+
+function writeImmutableBaseline(campaignDir, target, summary, scanPath) {
+  const baselinePath = path.join(campaignDir, target.baselineFile);
+  const value = summary[target.baselineField] ?? summary.clone_groups ?? summary.health_score ?? null;
+  const baseline = {
+    [target.baselineField]: value,
+    fallow_scan_path: scanPath,
+    recorded_at: isoNow(),
+    immutable: true,
+    source: "fallow-scan",
+    layer: target.id,
+    summary,
+  };
+  writeJson(baselinePath, baseline);
+  return baseline;
+}
+
+const args = parseArgs(process.argv.slice(2));
+if (!args.campaignId) {
+  console.error("fallow-scan: --campaign-id required");
+  process.exit(2);
+}
+
+const campaignDir = path.join(CAMPAIGNS_ROOT, args.campaignId);
+const iterDir = path.join(campaignDir, "iterations", String(args.iteration));
+fs.mkdirSync(iterDir, { recursive: true });
+
+const layers = {};
+let anyRuntimeError = false;
+
+for (const target of SCAN_TARGETS) {
+  const outPath = path.join(iterDir, target.outFile);
+  const run = runFallow(target.subcommand, target.extraArgs);
+  const payload = run.payload ?? { error: true, message: "no payload" };
+  const summary = target.summarize(payload);
+
+  if (!run.ok) anyRuntimeError = true;
+
+  const remediationMeta = {
+    layer: target.id,
+    scanned_at: isoNow(),
+    root: FRONTEND_ROOT,
+    exit_code: run.exit_code,
+    summary,
+    raw_path: outPath,
+  };
+
+  writeJson(outPath, { ...payload, _remediation: remediationMeta });
+  layers[target.id] = { summary, exit_code: run.exit_code, path: outPath, ok: run.ok };
+}
+
+const bundlePath = path.join(iterDir, "fallow-scan-bundle.json");
+const bundle = {
+  scanned_at: isoNow(),
+  root: FRONTEND_ROOT,
+  scope_note:
+    "Fallow v2 suite from frontend/ (dead-code + dupes + health). Backend Go and python/ verified via go test / pytest in verify gate.",
+  layers: {
+    dead_code: layers["dead-code"],
+    dupes: layers.dupes,
+    health: layers.health,
+  },
+};
+writeJson(bundlePath, bundle);
+
+const deadSummary = layers["dead-code"].summary;
+const dupesSummary = layers.dupes.summary;
+const healthSummary = layers.health.summary;
+
+const campaign = readJson(path.join(campaignDir, "campaign.json"));
+const startBaselinePath = path.join(campaignDir, "fallow-start-baseline.json");
+
+if (campaign) {
+  campaign.current = campaign.current ?? {};
+  campaign.current.fallow_total_issues = deadSummary.total_issues;
+  campaign.current.fallow_dupes_clone_groups = dupesSummary.clone_groups;
+  campaign.current.fallow_health_score = healthSummary.health_score;
+  campaign.updated_at = isoNow();
+
+  const iterBaselinePath = path.join(iterDir, "iteration-baseline.json");
+  if (args.saveBaseline) {
+    writeJson(iterBaselinePath, {
+      iteration: args.iteration,
+      fallow_total_issues: deadSummary.total_issues,
+      fallow_dupes_clone_groups: dupesSummary.clone_groups,
+      fallow_dupes_duplication_percentage: dupesSummary.duplication_percentage,
+      fallow_health_score: healthSummary.health_score,
+      fallow_health_functions_above_threshold: healthSummary.functions_above_threshold,
+      fallow_scan_path: path.join(iterDir, "fallow-scan.json"),
+      fallow_dupes_path: path.join(iterDir, "fallow-dupes.json"),
+      fallow_health_path: path.join(iterDir, "fallow-health.json"),
+      recorded_at: isoNow(),
+    });
+  }
+
+  if (args.saveBaseline && !fs.existsSync(startBaselinePath)) {
+    const baseline = writeImmutableBaseline(
+      campaignDir,
+      SCAN_TARGETS[0],
+      deadSummary,
+      path.join(iterDir, "fallow-scan.json"),
+    );
+    campaign.baseline = { ...campaign.baseline, ...baseline };
+    fs.appendFileSync(
+      path.join(campaignDir, "journal.md"),
+      `\n- **Fallow start baseline captured** (immutable) — dead-code total=${deadSummary.total_issues}\n`,
+    );
+  } else if (fs.existsSync(startBaselinePath)) {
+    campaign.baseline = { ...campaign.baseline, ...readJson(startBaselinePath, {}) };
+  }
+
+  for (const target of SCAN_TARGETS.slice(1)) {
+    const baselinePath = path.join(campaignDir, target.baselineFile);
+    if (!fs.existsSync(baselinePath)) {
+      const summary = layers[target.id].summary;
+      const baseline = writeImmutableBaseline(
+        campaignDir,
+        target,
+        summary,
+        path.join(iterDir, target.outFile),
+      );
+      campaign.baseline = { ...campaign.baseline, ...baseline };
+      fs.appendFileSync(
+        path.join(campaignDir, "journal.md"),
+        `- **Fallow ${target.id} baseline backfilled** — ${target.baselineField}=${baseline[target.baselineField]}\n`,
+      );
+    }
+  }
+
+  writeJson(path.join(campaignDir, "campaign.json"), campaign);
+}
+
+const classifyArgs = [
+  path.join(__dirname, "classify-fallow-issues.mjs"),
+  "--campaign-id",
+  args.campaignId,
+  "--iteration",
+  String(args.iteration),
+];
+if (args.saveBaseline) classifyArgs.push("--save-actionable-baseline");
+spawnSync(process.execPath, classifyArgs, { encoding: "utf8" });
+
+console.log(
+  JSON.stringify({
+    ok: !anyRuntimeError,
+    summary: deadSummary,
+    dupes: dupesSummary,
+    health: healthSummary,
+    path: path.join(iterDir, "fallow-scan.json"),
+    bundle_path: bundlePath,
+  }),
+);

package/templates/cursor/aaac/scripts/remediation/handle-yield.mjs

@@ -0,0 +1,240 @@
+#!/usr/bin/env node
+/**
+ * Handle a runner yield — scriptable steps + Cursor agent for code waves.
+ */
+import fs from "fs";
+import path from "path";
+import { spawnSync } from "child_process";
+import { REPO_ROOT, readJson, writeJson, isoNow } from "../run-engine/lib.mjs";
+import {
+  campaignDir,
+  iterDir,
+  loadYield,
+  runArtifactsDir,
+} from "./lib/runner-state.mjs";
+import { loadCampaignContext } from "./lib/campaign-focus.mjs";
+import { invokeCursorAgent } from "./lib/invoke-cursor-agent.mjs";
+import { runNode, parseDispatchQueueYaml, journal } from "./lib/runner-exec.mjs";
+
+function parseArgs(argv) {
+  const out = { runId: null, campaignId: null };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--run-id") out.runId = argv[++i];
+    else if (argv[i] === "--campaign-id") out.campaignId = argv[++i];
+  }
+  return out;
+}
+
+function readWave(campaignId, runId, waveIndex) {
+  const queuePath = path.join(campaignDir(campaignId), "dispatch-queue.yaml");
+  if (fs.existsSync(queuePath)) {
+    const waves = parseDispatchQueueYaml(fs.readFileSync(queuePath, "utf8"));
+    if (waves[waveIndex]) return waves[waveIndex];
+  }
+  const planPath = path.join(runArtifactsDir(runId), "plan_waves.yaml");
+  if (fs.existsSync(planPath)) {
+    const waves = parseDispatchQueueYaml(fs.readFileSync(planPath, "utf8"));
+    if (waves[waveIndex]) return waves[waveIndex];
+  }
+  return { index: waveIndex, command: "fix-module", intent: `Health wave ${waveIndex}`, risk: "low" };
+}
+
+function recordExecuteWave(campaignId, iteration, waveIndex, wave, status = "completed") {
+  const artifact = path.join(campaignDir(campaignId), "artifacts", "execute_waves.json");
+  const data = readJson(artifact, { campaign_id: campaignId, iteration, waves: [] });
+  data.iteration = iteration;
+  data.waves = (data.waves ?? []).filter((w) => w.index !== waveIndex);
+  data.waves.push({
+    index: waveIndex,
+    priority: wave.priority ?? waveIndex + 1,
+    command: wave.command ?? "fix-module",
+    status,
+    risk: wave.risk ?? "low",
+    intent: wave.intent ?? "",
+    completed_at: isoNow(),
+  });
+  writeJson(artifact, data);
+}
+
+function buildWavePrompt(ctx, yieldPayload, wave) {
+  const protectedList = ctx.protected_paths.map((p) => `- ${p}`).join("\n");
+  return [
+    "You are executing a remediation campaign wave. Follow instructions exactly.",
+    "",
+    `Campaign intent: ${ctx.campaign.intent}`,
+    `Focus: reduce functions over ${ctx.focus.max_function_loc} LOC (health decomposition)`,
+    `Iteration: ${yieldPayload.iteration}`,
+    `Wave ${yieldPayload.wave_index + 1} of ${yieldPayload.wave_total ?? "?"}`,
+    "",
+    "Wave intent:",
+    wave.intent || yieldPayload.intent,
+    "",
+    "Protected paths — NEVER modify, delete, or split these files:",
+    protectedList,
+    "",
+    "Rules:",
+    "- Work in frontend/ when paths start with src/",
+    "- Split large functions into focused modules; each function should be <= 60 LOC where practical",
+    "- Preserve exports and public API; composition roots stay thin",
+    "- Match existing code conventions",
+    "- Run: cd frontend && pnpm exec tsc --noEmit — fix any errors you introduce",
+    "- Do not commit",
+  ].join("\n");
+}
+
+function buildRemediatorPrompt(ctx, yieldPayload, handoff) {
+  const logHint = handoff.log_path ? `Read full log: ${handoff.log_path}` : "";
+  return [
+    "Fix remediation verify/debt-sweep failures introduced by the last wave.",
+    "",
+    `Campaign intent: ${ctx.campaign.intent}`,
+    `Mode: ${handoff.mode ?? yieldPayload.phase}`,
+    `Layer: ${handoff.layer ?? "unknown"}`,
+    "",
+    handoff.intent ?? handoff.message ?? "",
+    logHint,
+    "",
+    "Fix only what is required to pass verification. Run tsc and relevant tests.",
+  ].join("\n");
+}
+
+function handleCheckSwarm(args, ctx, yieldPayload) {
+  const n = yieldPayload.iteration;
+  const synth = runNode("auto-check-swarm-synthesis.mjs", [
+    "--campaign-id", args.campaignId, "--iteration", String(n),
+  ]);
+  if (!synth.ok) throw new Error(`auto-check-swarm-synthesis failed: ${synth.stderr}`);
+
+  const merge = runNode("merge-check-swarm.mjs", [
+    "--campaign-id", args.campaignId, "--iteration", String(n), "--run-id", args.runId,
+  ]);
+  if (!merge.ok) throw new Error(`merge-check-swarm failed: ${merge.stderr}`);
+
+  const dispatch = runNode("auto-dispatch-queue-from-health.mjs", [
+    "--campaign-id", args.campaignId, "--iteration", String(n),
+  ]);
+  if (!dispatch.ok) throw new Error(`auto-dispatch-queue failed: ${dispatch.stderr}`);
+
+  const synthesis = `# Auto check synthesis iter ${n}\n\nFocus: ${ctx.focus.health_functions_above_60_loc ? "Health Functions >60 LOC" : "general"}\n`;
+  fs.writeFileSync(path.join(campaignDir(args.campaignId), "artifacts", "check_synthesis.md"), synthesis);
+  journal(args.campaignId, `- **Yield handler** check_swarm iter ${n} (auto)`);
+  return "check_swarm";
+}
+
+function handleDispatchQueue(args, ctx, yieldPayload) {
+  const n = yieldPayload.iteration;
+  const dispatch = runNode("auto-dispatch-queue-from-health.mjs", [
+    "--campaign-id", args.campaignId, "--iteration", String(n),
+  ]);
+  if (!dispatch.ok) throw new Error(`auto-dispatch-queue failed: ${dispatch.stderr}`);
+  journal(args.campaignId, `- **Yield handler** dispatch_queue iter ${n}`);
+  return "dispatch_queue";
+}
+
+function runTsc(scope) {
+  const cwd = scope === "frontend" ? path.join(REPO_ROOT, "frontend") : REPO_ROOT;
+  return spawnSync("pnpm", ["exec", "tsc", "--noEmit"], { cwd, encoding: "utf8" });
+}
+
+function handleExecuteWave(args, ctx, yieldPayload) {
+  const waveIndex = yieldPayload.wave_index ?? 0;
+  const wave = readWave(args.campaignId, args.runId, waveIndex);
+  const logPath = path.join(
+    iterDir(args.campaignId, yieldPayload.iteration),
+    "verify-logs",
+    `yield-agent-wave-${waveIndex}.log`,
+  );
+  const prompt = buildWavePrompt(ctx, yieldPayload, wave);
+  const agent = invokeCursorAgent(prompt, { cwd: REPO_ROOT, logPath, timeoutMs: 1_200_000 });
+  if (!agent.ok) {
+    recordExecuteWave(args.campaignId, yieldPayload.iteration, waveIndex, wave, "degraded");
+    throw new Error(`cursor agent failed (${agent.status}): ${agent.stderr.slice(0, 500)}`);
+  }
+  const tsc = runTsc(ctx.scope);
+  if (tsc.status !== 0) {
+    recordExecuteWave(args.campaignId, yieldPayload.iteration, waveIndex, wave, "degraded");
+    throw new Error(`tsc failed after wave: ${(tsc.stderr || tsc.stdout).slice(0, 500)}`);
+  }
+  recordExecuteWave(args.campaignId, yieldPayload.iteration, waveIndex, wave, "completed");
+  journal(args.campaignId, `- **Yield handler** execute_wave ${waveIndex} iter ${yieldPayload.iteration}`);
+  return "execute_wave";
+}
+
+function handleRemediator(args, ctx, yieldPayload) {
+  const iterDirPath = iterDir(args.campaignId, yieldPayload.iteration);
+  const handoffFiles = fs.existsSync(iterDirPath)
+    ? fs.readdirSync(iterDirPath).filter((f) => f.startsWith("remediator-handoff-attempt-"))
+    : [];
+  handoffFiles.sort();
+  const latest = handoffFiles[handoffFiles.length - 1];
+  const handoff = latest ? readJson(path.join(iterDirPath, latest), {}) : {};
+  const logPath = path.join(iterDirPath, "verify-logs", `yield-agent-remediator-${yieldPayload.attempt ?? 1}.log`);
+  const prompt = buildRemediatorPrompt(ctx, yieldPayload, handoff);
+  const agent = invokeCursorAgent(prompt, { cwd: REPO_ROOT, logPath, timeoutMs: 900_000 });
+  if (!agent.ok) throw new Error(`remediator agent failed: ${agent.stderr.slice(0, 500)}`);
+  journal(args.campaignId, `- **Yield handler** remediator iter ${yieldPayload.iteration}`);
+  return "remediator";
+}
+
+function handleReport(args, ctx) {
+  const reportPath = path.join(campaignDir(args.campaignId), "artifacts", "report.md");
+  const history = path.join(campaignDir(args.campaignId), "satisfaction-history.yaml");
+  const body = [
+    "# Remediation report",
+    "",
+    `Campaign: ${args.campaignId}`,
+    `Intent: ${ctx.campaign.intent}`,
+    `Completed: ${isoNow()}`,
+    "",
+    fs.existsSync(history) ? fs.readFileSync(history, "utf8") : "",
+  ].join("\n");
+  fs.writeFileSync(reportPath, body);
+  journal(args.campaignId, "- **Yield handler** report written");
+  return "report";
+}
+
+const args = parseArgs(process.argv.slice(2));
+if (!args.runId || !args.campaignId) {
+  console.error("Usage: handle-yield.mjs --run-id <id> --campaign-id <id>");
+  process.exit(2);
+}
+
+const yieldPayload = loadYield(args.campaignId);
+if (!yieldPayload?.type) {
+  console.error("No pending yield");
+  process.exit(2);
+}
+
+const ctx = loadCampaignContext(args.campaignId);
+if (!ctx) {
+  console.error("Campaign not found");
+  process.exit(2);
+}
+
+let ackType;
+try {
+  switch (yieldPayload.type) {
+    case "check_swarm":
+      ackType = handleCheckSwarm(args, ctx, yieldPayload);
+      break;
+    case "dispatch_queue":
+      ackType = handleDispatchQueue(args, ctx, yieldPayload);
+      break;
+    case "execute_wave":
+      ackType = handleExecuteWave(args, ctx, yieldPayload);
+      break;
+    case "remediator":
+      ackType = handleRemediator(args, ctx, yieldPayload);
+      break;
+    case "report":
+      ackType = handleReport(args, ctx);
+      break;
+    default:
+      throw new Error(`Unknown yield type: ${yieldPayload.type}`);
+  }
+} catch (err) {
+  console.error(JSON.stringify({ ok: false, error: String(err?.message ?? err), yield: yieldPayload.type }));
+  process.exit(1);
+}
+
+console.log(JSON.stringify({ ok: true, ack_type: ackType, yield: yieldPayload.type }));

package/templates/cursor/aaac/scripts/remediation/init-campaign.mjs

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+/**
+ * Initialize or resume a remediation campaign for /remediate-app.
+ *
+ * Usage:
+ *   node init-campaign.mjs --run-id <run_id> [--campaign-id <id>] [--resume <id>]
+ */
+import fs from "fs";
+import path from "path";
+import { spawnSync } from "child_process";
+import { fileURLToPath } from "url";
+import {
+  REPO_ROOT,
+  isoNow,
+  readJson,
+  runDir,
+  slugify,
+  writeJson,
+} from "../run-engine/lib.mjs";
+import { applyAutonomousToConfig } from "./lib/autonomous-mode.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const BOOTSTRAP_SCRIPT = path.join(__dirname, "bootstrap-autonomous.mjs");
+const CAMPAIGNS_ROOT = path.join(REPO_ROOT, ".cursor/aaac/state/campaigns");
+
+function parseArgs(argv) {
+  const out = {
+    runId: null,
+    campaignId: null,
+    resume: null,
+    scope: "whole-repo",
+    intent: "",
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--run-id") out.runId = argv[++i];
+    else if (a === "--campaign-id") out.campaignId = argv[++i];
+    else if (a === "--resume") out.resume = argv[++i];
+    else if (a === "--scope") out.scope = argv[++i];
+    else if (a === "--intent") out.intent = argv[++i];
+  }
+  return out;
+}
+
+function parseIntentConfig(intent) {
+  const base = {
+    max_iterations: 5,
+    max_waves_per_iteration: 3,
+    max_remediator_attempts_per_wave: 3,
+    max_remediator_attempts_per_iteration: 3,
+    max_remediator_attempts_per_debt_round: 3,
+    max_debt_sweep_rounds: 10,
+    wave_gate_mode: "regression",
+    debt_gate_mode: "strict",
+    satisfaction_threshold: 85,
+    rollback_on_verify_fail: true,
+  };
+  if (!intent) return applyAutonomousToConfig(base, intent);
+  const maxIter = intent.match(/max_iterations\s*=\s*(\d+)/i);
+  if (maxIter) base.max_iterations = Number(maxIter[1]);
+  const maxWaves = intent.match(/max_waves_per_iteration\s*=\s*(\d+)/i);
+  if (maxWaves) base.max_waves_per_iteration = Number(maxWaves[1]);
+  const maxRemWave = intent.match(/max_remediator_attempts_per_wave\s*=\s*(\d+)/i);
+  if (maxRemWave) base.max_remediator_attempts_per_wave = Number(maxRemWave[1]);
+  const maxRemIter = intent.match(/max_remediator_attempts_per_iteration\s*=\s*(\d+)/i);
+  if (maxRemIter) base.max_remediator_attempts_per_iteration = Number(maxRemIter[1]);
+  const maxDebtRounds = intent.match(/max_debt_sweep_rounds\s*=\s*(\d+)/i);
+  if (maxDebtRounds) base.max_debt_sweep_rounds = Number(maxDebtRounds[1]);
+  const maxDebtAttempts = intent.match(/max_remediator_attempts_per_debt_round\s*=\s*(\d+)/i);
+  if (maxDebtAttempts) base.max_remediator_attempts_per_debt_round = Number(maxDebtAttempts[1]);
+  const threshold = intent.match(/satisfaction_threshold\s*=\s*(\d+)/i);
+  if (threshold) base.satisfaction_threshold = Number(threshold[1]);
+  return applyAutonomousToConfig(base, intent);
+}
+
+function campaignDir(campaignId) {
+  return path.join(CAMPAIGNS_ROOT, campaignId);
+}
+
+function appendJournal(campaignId, line) {
+  const journalPath = path.join(campaignDir(campaignId), "journal.md");
+  const header =
+    fs.existsSync(journalPath) ? "" : "# Remediation campaign journal\n\n";
+  fs.appendFileSync(journalPath, `${header}${line}\n`);
+}
+
+const args = parseArgs(process.argv.slice(2));
+if (!args.runId) {
+  console.error("init-campaign: --run-id required");
+  process.exit(2);
+}
+
+const manifest = readJson(path.join(runDir(args.runId), "run.json"), {});
+const intent = args.intent || manifest.intent || "";
+const config = parseIntentConfig(intent);
+
+let campaignId = args.resume || args.campaignId;
+const now = isoNow();
+const date = now.slice(0, 10).replace(/-/g, "");
+
+if (!campaignId) {
+  const resumeMatch = intent.match(/resume\s+(campaign_[a-z0-9_-]+)/i);
+  campaignId = resumeMatch?.[1] ?? `campaign_${date}_${slugify(manifest.command ?? "remediate")}`;
+}
+
+const dir = campaignDir(campaignId);
+fs.mkdirSync(path.join(dir, "iterations"), { recursive: true });
+
+const isResume = Boolean(args.resume || intent.match(/resume/i));
+let campaign = readJson(path.join(dir, "campaign.json"), null);
+if (campaign && !isResume) {
+  campaign = null;
+}
+
+if (!campaign) {
+  campaign = {
+    campaign_id: campaignId,
+    run_id: args.runId,
+    conversation_id: manifest.conversation_id ?? null,
+    scope: args.scope,
+    status: "running",
+    intent,
+    config,
+    iteration: 0,
+    waves_completed_total: 0,
+    baseline: {
+      fallow_total_issues: null,
+      fallow_scan_path: null,
+      clone_groups: null,
+      health_score: null,
+      recorded_at: null,
+    },
+    current: {
+      fallow_total_issues: null,
+      fallow_dupes_clone_groups: null,
+      fallow_health_score: null,
+      satisfaction_score: null,
+      satisfaction_rate: null,
+      e2e_pass: null,
+      verify_status: null,
+    },
+    dispatch_queue_path: "dispatch-queue.yaml",
+    debt_sweep: { status: "pending", iteration: null },
+    verify_baseline: null,
+    created_at: now,
+    updated_at: now,
+  };
+  writeJson(path.join(dir, "campaign.json"), campaign);
+  writeJson(path.join(dir, "satisfaction-history.yaml"), { entries: [] });
+  appendJournal(
+    campaignId,
+    `## ${now} — Campaign started\n\n- **Run:** \`${args.runId}\`\n- **Scope:** ${args.scope}\n- **Config:** max_iterations=${config.max_iterations}, threshold=${config.satisfaction_threshold}, autonomous=${config.autonomous}\n`,
+  );
+} else {
+  campaign.run_id = args.runId;
+  campaign.intent = intent || campaign.intent;
+  campaign.config = { ...campaign.config, ...config };
+  campaign.updated_at = now;
+  campaign.status = "running";
+  writeJson(path.join(dir, "campaign.json"), campaign);
+  appendJournal(
+    campaignId,
+    `## ${now} — Campaign resumed\n\n- **Run:** \`${args.runId}\`\n- **Iteration:** ${campaign.iteration}\n- **Autonomous:** ${campaign.config.autonomous} (${campaign.config.autonomous_reason})\n`,
+  );
+}
+
+const artifactPath = path.join(runDir(args.runId), "artifacts/campaign.json");
+writeJson(artifactPath, {
+  campaign_id: campaignId,
+  campaign_dir: dir,
+  config: campaign.config,
+  status: campaign.status,
+  iteration: campaign.iteration,
+  autonomous: campaign.config.autonomous,
+});
+
+let bootstrap = null;
+if (campaign.config.autonomous) {
+  const boot = spawnSync(
+    process.execPath,
+    [BOOTSTRAP_SCRIPT, "--run-id", args.runId, "--campaign-id", campaignId],
+    { encoding: "utf8" },
+  );
+  try {
+    bootstrap = JSON.parse(boot.stdout.trim().split("\n").pop());
+  } catch {
+    bootstrap = { ok: false, error: boot.stderr || "bootstrap parse failed" };
+  }
+}
+
+const out = {
+  ok: true,
+  campaign_id: campaignId,
+  campaign_dir: dir,
+  iteration: campaign.iteration,
+  config: campaign.config,
+  autonomous: campaign.config.autonomous,
+  autonomous_reason: campaign.config.autonomous_reason,
+  orchestrator_mode: campaign.config.runner_mode,
+  bootstrap,
+};
+
+if (campaign.config.autonomous && bootstrap?.next_action) {
+  out.orchestrator_must = {
+    read_skill: bootstrap.skill_required,
+    next_action: bootstrap.next_action,
+    must_not_end_turn_until: "remediation-runner exit 0 or blocked",
+  };
+}
+
+console.log(JSON.stringify(out));