codeharness 0.18.1 → 0.19.2

package/dist/index.js

@@ -940,14 +940,9 @@ import { join as join5, dirname as dirname2 } from "path";
 import { fileURLToPath } from "url";
 var __dirname = dirname2(fileURLToPath(import.meta.url));
 function readPatchFile(name) {
-  const projectRoot = join5(__dirname, "..", "..");
-  const projectPath = join5(projectRoot, "patches", `${name}.md`);
-  if (existsSync5(projectPath)) {
-    return readFileSync5(projectPath, "utf-8").trim();
-  }
-  const pkgPath = join5(__dirname, "..", "..", "patches", `${name}.md`);
-  if (existsSync5(pkgPath)) {
-    return readFileSync5(pkgPath, "utf-8").trim();
+  const patchPath = join5(__dirname, "..", "..", "patches", `${name}.md`);
+  if (existsSync5(patchPath)) {
+    return readFileSync5(patchPath, "utf-8").trim();
   }
   return null;
 }
@@ -1392,7 +1387,7 @@ function getInstallCommand(stack) {
 }
 
 // src/commands/init.ts
-var HARNESS_VERSION = true ? "0.18.1" : "0.0.0-dev";
+var HARNESS_VERSION = true ? "0.19.2" : "0.0.0-dev";
 function getProjectName(projectDir) {
   try {
     const pkgPath = join7(projectDir, "package.json");
@@ -1506,8 +1501,8 @@ function registerInitCommand(program) {
         readme: "skipped"
       }
     };
-    const statePath = getStatePath(projectDir);
-    if (existsSync7(statePath)) {
+    const statePath2 = getStatePath(projectDir);
+    if (existsSync7(statePath2)) {
       try {
         const existingState = readState(projectDir);
         const legacyObsDisabled = existingState.enforcement.observability === false;
@@ -2591,7 +2586,7 @@ function buildSpawnArgs(opts) {
   return args;
 }
 function registerRunCommand(program) {
-  program.command("run").description("Execute the autonomous coding loop").option("--max-iterations <n>", "Maximum loop iterations", "50").option("--timeout <seconds>", "Total loop timeout in seconds", "14400").option("--iteration-timeout <minutes>", "Per-iteration timeout in minutes", "30").option("--live", "Show live output streaming", false).option("--calls <n>", "Max API calls per hour", "100").option("--max-story-retries <n>", "Max retries per story before flagging", "3").option("--reset", "Clear retry counters, flagged stories, and circuit breaker before starting", false).action(async (options, cmd) => {
+  program.command("run").description("Execute the autonomous coding loop").option("--max-iterations <n>", "Maximum loop iterations", "50").option("--timeout <seconds>", "Total loop timeout in seconds", "14400").option("--iteration-timeout <minutes>", "Per-iteration timeout in minutes", "30").option("--live", "Show live output streaming", false).option("--calls <n>", "Max API calls per hour", "100").option("--max-story-retries <n>", "Max retries per story before flagging", "10").option("--reset", "Clear retry counters, flagged stories, and circuit breaker before starting", false).action(async (options, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
     const isJson = !!globalOpts.json;
     const outputOpts = { json: isJson };
@@ -2673,12 +2668,12 @@ function registerRunCommand(program) {
         cwd: projectDir,
         env
       });
-      const exitCode = await new Promise((resolve, reject) => {
+      const exitCode = await new Promise((resolve2, reject) => {
         child.on("error", (err) => {
           reject(err);
         });
         child.on("close", (code) => {
-          resolve(code ?? 1);
+          resolve2(code ?? 1);
         });
       });
       if (isJson) {
@@ -4324,8 +4319,8 @@ function printCoverageOutput(result, evaluation) {
 
 // src/lib/onboard-checks.ts
 function checkHarnessInitialized(dir) {
-  const statePath = getStatePath(dir ?? process.cwd());
-  return { ok: existsSync16(statePath) };
+  const statePath2 = getStatePath(dir ?? process.cwd());
+  return { ok: existsSync16(statePath2) };
 }
 function checkBmadInstalled(dir) {
   return { ok: isBmadInstalled(dir) };
@@ -4502,6 +4497,644 @@ function filterTrackedGaps(stories, beadsFns) {
   return { untracked, trackedCount };
 }
 
+// src/types/result.ts
+function ok2(data) {
+  return { success: true, data };
+}
+function fail2(error, context) {
+  if (context !== void 0) {
+    return { success: false, error, context };
+  }
+  return { success: false, error };
+}
+
+// src/modules/sprint/state.ts
+import { readFileSync as readFileSync16, writeFileSync as writeFileSync9, renameSync, existsSync as existsSync18 } from "fs";
+import { join as join16 } from "path";
+
+// src/modules/sprint/migration.ts
+import { readFileSync as readFileSync15, existsSync as existsSync17 } from "fs";
+import { join as join15 } from "path";
+var OLD_FILES = {
+  storyRetries: "ralph/.story_retries",
+  flaggedStories: "ralph/.flagged_stories",
+  ralphStatus: "ralph/status.json",
+  sprintStatusYaml: "_bmad-output/implementation-artifacts/sprint-status.yaml",
+  sessionIssues: "_bmad-output/implementation-artifacts/.session-issues.md"
+};
+function resolve(relative3) {
+  return join15(process.cwd(), relative3);
+}
+function readIfExists(relative3) {
+  const p = resolve(relative3);
+  if (!existsSync17(p)) return null;
+  try {
+    return readFileSync15(p, "utf-8");
+  } catch {
+    return null;
+  }
+}
+function emptyStory() {
+  return {
+    status: "backlog",
+    attempts: 0,
+    lastAttempt: null,
+    lastError: null,
+    proofPath: null,
+    acResults: null
+  };
+}
+function upsertStory(stories, key, patch) {
+  stories[key] = { ...stories[key] ?? emptyStory(), ...patch };
+}
+function parseStoryRetries(content, stories) {
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const parts = trimmed.split(/\s+/);
+    if (parts.length < 2) continue;
+    const count = parseInt(parts[1], 10);
+    if (!isNaN(count)) upsertStory(stories, parts[0], { attempts: count });
+  }
+}
+function parseFlaggedStories(content, stories) {
+  for (const line of content.split("\n")) {
+    const key = line.trim();
+    if (key) upsertStory(stories, key, { status: "blocked" });
+  }
+}
+function mapYamlStatus(value) {
+  const mapping = {
+    done: "done",
+    backlog: "backlog",
+    verifying: "verifying",
+    "in-progress": "in-progress",
+    "ready-for-dev": "ready",
+    blocked: "blocked",
+    failed: "failed",
+    review: "review",
+    ready: "ready"
+  };
+  return mapping[value.trim().toLowerCase()] ?? null;
+}
+function parseSprintStatusYaml(content, stories) {
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const match = trimmed.match(/^([a-zA-Z0-9_-]+):\s*(.+)$/);
+    if (!match) continue;
+    const key = match[1];
+    if (key === "development_status" || key.startsWith("epic-")) continue;
+    const status = mapYamlStatus(match[2]);
+    if (status) upsertStory(stories, key, { status });
+  }
+}
+function parseRalphStatus(content) {
+  try {
+    const data = JSON.parse(content);
+    return {
+      active: data.status === "running",
+      startedAt: null,
+      iteration: data.loop_count ?? 0,
+      cost: 0,
+      completed: [],
+      failed: []
+    };
+  } catch {
+    return null;
+  }
+}
+function parseSessionIssues(content) {
+  const items = [];
+  let currentStory = "";
+  let itemId = 0;
+  for (const line of content.split("\n")) {
+    const headerMatch = line.match(/^###\s+([a-zA-Z0-9_-]+)\s*[—-]/);
+    if (headerMatch) {
+      currentStory = headerMatch[1];
+      continue;
+    }
+    const bulletMatch = line.match(/^-\s+(.+)/);
+    if (bulletMatch && currentStory) {
+      itemId++;
+      items.push({
+        id: `migrated-${itemId}`,
+        story: currentStory,
+        description: bulletMatch[1],
+        source: "retro",
+        resolved: false
+      });
+    }
+  }
+  return items;
+}
+function migrateFromOldFormat() {
+  const hasAnyOldFile = Object.values(OLD_FILES).some((rel) => existsSync17(resolve(rel)));
+  if (!hasAnyOldFile) return fail2("No old format files found for migration");
+  try {
+    const stories = {};
+    let run = defaultState().run;
+    let actionItems = [];
+    const yamlContent = readIfExists(OLD_FILES.sprintStatusYaml);
+    if (yamlContent) parseSprintStatusYaml(yamlContent, stories);
+    const retriesContent = readIfExists(OLD_FILES.storyRetries);
+    if (retriesContent) parseStoryRetries(retriesContent, stories);
+    const flaggedContent = readIfExists(OLD_FILES.flaggedStories);
+    if (flaggedContent) parseFlaggedStories(flaggedContent, stories);
+    const statusContent = readIfExists(OLD_FILES.ralphStatus);
+    if (statusContent) {
+      const parsed = parseRalphStatus(statusContent);
+      if (parsed) run = parsed;
+    }
+    const issuesContent = readIfExists(OLD_FILES.sessionIssues);
+    if (issuesContent) actionItems = parseSessionIssues(issuesContent);
+    const sprint = computeSprintCounts(stories);
+    const migrated = {
+      version: 1,
+      sprint,
+      stories,
+      run,
+      actionItems
+    };
+    const writeResult = writeStateAtomic(migrated);
+    if (!writeResult.success) return fail2(writeResult.error);
+    return ok2(migrated);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return fail2(`Migration failed: ${msg}`);
+  }
+}
+
+// src/modules/sprint/state.ts
+function projectRoot() {
+  return process.cwd();
+}
+function statePath() {
+  return join16(projectRoot(), "sprint-state.json");
+}
+function tmpPath() {
+  return join16(projectRoot(), ".sprint-state.json.tmp");
+}
+function defaultState() {
+  return {
+    version: 1,
+    sprint: {
+      total: 0,
+      done: 0,
+      failed: 0,
+      blocked: 0,
+      inProgress: null
+    },
+    stories: {},
+    run: {
+      active: false,
+      startedAt: null,
+      iteration: 0,
+      cost: 0,
+      completed: [],
+      failed: []
+    },
+    actionItems: []
+  };
+}
+function writeStateAtomic(state) {
+  try {
+    const data = JSON.stringify(state, null, 2) + "\n";
+    const tmp = tmpPath();
+    const final = statePath();
+    writeFileSync9(tmp, data, "utf-8");
+    renameSync(tmp, final);
+    return ok2(void 0);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return fail2(`Failed to write sprint state: ${msg}`);
+  }
+}
+function getSprintState() {
+  const fp = statePath();
+  if (existsSync18(fp)) {
+    try {
+      const raw = readFileSync16(fp, "utf-8");
+      const parsed = JSON.parse(raw);
+      return ok2(parsed);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return fail2(`Failed to read sprint state: ${msg}`);
+    }
+  }
+  const migrationResult = migrateFromOldFormat();
+  if (migrationResult.success) {
+    return migrationResult;
+  }
+  return ok2(defaultState());
+}
+function computeSprintCounts(stories) {
+  let total = 0;
+  let done = 0;
+  let failed = 0;
+  let blocked = 0;
+  let inProgress = null;
+  for (const [key, story] of Object.entries(stories)) {
+    total++;
+    if (story.status === "done") done++;
+    else if (story.status === "failed") failed++;
+    else if (story.status === "blocked") blocked++;
+    else if (story.status === "in-progress") inProgress = key;
+  }
+  return { total, done, failed, blocked, inProgress };
+}
+
+// src/modules/sprint/selector.ts
+var MAX_STORY_ATTEMPTS = 10;
+
+// src/modules/sprint/drill-down.ts
+var MAX_ATTEMPTS = MAX_STORY_ATTEMPTS;
+function epicPrefix(key) {
+  const dashIdx = key.indexOf("-");
+  if (dashIdx === -1) return key;
+  return key.slice(0, dashIdx);
+}
+function buildAcDetails(story) {
+  if (!story.acResults) return [];
+  return story.acResults.map((ac) => {
+    const detail = { id: ac.id, verdict: ac.verdict };
+    if (ac.verdict === "fail" && story.lastError) {
+      return { ...detail, reason: story.lastError };
+    }
+    return detail;
+  });
+}
+function buildAttemptHistory(story) {
+  const records = [];
+  if (story.attempts === 0) return records;
+  for (let i = 1; i < story.attempts; i++) {
+    records.push({
+      number: i,
+      outcome: "details unavailable"
+    });
+  }
+  const lastOutcome = story.status === "done" ? "passed" : story.status === "failed" ? "verify failed" : story.status === "blocked" ? "blocked" : story.status;
+  const lastRecord = {
+    number: story.attempts,
+    outcome: lastOutcome,
+    ...story.lastAttempt ? { timestamp: story.lastAttempt } : {}
+  };
+  if (story.acResults) {
+    const failingAc = story.acResults.find((ac) => ac.verdict === "fail");
+    if (failingAc) {
+      records.push({ ...lastRecord, failingAc: failingAc.id });
+      return records;
+    }
+  }
+  records.push(lastRecord);
+  return records;
+}
+function buildProofSummary(story) {
+  if (!story.proofPath) return null;
+  let passCount = 0;
+  let failCount = 0;
+  let escalateCount = 0;
+  let pendingCount = 0;
+  if (story.acResults) {
+    for (const ac of story.acResults) {
+      if (ac.verdict === "pass") passCount++;
+      else if (ac.verdict === "fail") failCount++;
+      else if (ac.verdict === "escalate") escalateCount++;
+      else if (ac.verdict === "pending") pendingCount++;
+    }
+  }
+  return { path: story.proofPath, passCount, failCount, escalateCount, pendingCount };
+}
+function getStoryDrillDown(state, key) {
+  try {
+    const story = state.stories[key];
+    if (!story) {
+      return fail2(`Story '${key}' not found in sprint state`);
+    }
+    const epic = epicPrefix(key);
+    const acDetails = buildAcDetails(story);
+    const attemptHistory = buildAttemptHistory(story);
+    const proofSummary = buildProofSummary(story);
+    return ok2({
+      key,
+      status: story.status,
+      epic,
+      attempts: story.attempts,
+      maxAttempts: MAX_ATTEMPTS,
+      lastAttempt: story.lastAttempt,
+      acDetails,
+      attemptHistory,
+      proofSummary
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return fail2(`Failed to get story drill-down: ${msg}`);
+  }
+}
+
+// src/modules/sprint/reporter.ts
+var MAX_ATTEMPTS2 = MAX_STORY_ATTEMPTS;
+function formatDuration(ms) {
+  const clamped = Math.max(0, ms);
+  const totalMinutes = Math.floor(clamped / 6e4);
+  const hours = Math.floor(totalMinutes / 60);
+  const minutes = totalMinutes % 60;
+  if (hours > 0) return `${hours}h${minutes}m`;
+  return `${minutes}m`;
+}
+function computeEpicProgress(stories) {
+  const epicGroups = /* @__PURE__ */ new Map();
+  for (const [key, story] of Object.entries(stories)) {
+    const prefix = epicPrefix(key);
+    const group = epicGroups.get(prefix) ?? { total: 0, done: 0 };
+    group.total++;
+    if (story.status === "done") group.done++;
+    epicGroups.set(prefix, group);
+  }
+  let epicsTotal = 0;
+  let epicsDone = 0;
+  for (const group of epicGroups.values()) {
+    epicsTotal++;
+    if (group.total > 0 && group.done === group.total) epicsDone++;
+  }
+  return { epicsTotal, epicsDone };
+}
+function buildFailedDetails(stories) {
+  const details = [];
+  for (const [key, story] of Object.entries(stories)) {
+    if (story.status !== "failed") continue;
+    let acNumber = null;
+    if (story.acResults) {
+      for (const ac of story.acResults) {
+        if (ac.verdict === "fail") {
+          const num = parseInt(ac.id.replace(/\D/g, ""), 10);
+          if (!isNaN(num)) {
+            acNumber = num;
+            break;
+          }
+        }
+      }
+    }
+    details.push({
+      key,
+      acNumber,
+      errorLine: story.lastError ?? "unknown error",
+      attempts: story.attempts,
+      maxAttempts: MAX_ATTEMPTS2
+    });
+  }
+  return details;
+}
+function buildActionItemsLabeled(state) {
+  const runStories = /* @__PURE__ */ new Set([
+    ...state.run.completed,
+    ...state.run.failed
+  ]);
+  return state.actionItems.map((item) => {
+    const isNew = item.source === "verification" && runStories.has(item.story);
+    return { item, label: isNew ? "NEW" : "CARRIED" };
+  });
+}
+function buildRunSummary(state, now) {
+  if (!state.run.startedAt) return null;
+  const startedAt = new Date(state.run.startedAt);
+  const elapsed = now.getTime() - startedAt.getTime();
+  const blocked = [];
+  const skipped = [];
+  for (const [key, story] of Object.entries(state.stories)) {
+    if (story.status === "blocked") {
+      blocked.push(key);
+      if (story.attempts >= MAX_ATTEMPTS2) {
+        skipped.push(key);
+      }
+    }
+  }
+  return {
+    duration: formatDuration(elapsed),
+    cost: state.run.cost,
+    iterations: state.run.iteration,
+    completed: [...state.run.completed],
+    failed: [...state.run.failed],
+    blocked,
+    skipped
+  };
+}
+function generateReport(state, now) {
+  try {
+    const effectiveNow = now ?? /* @__PURE__ */ new Date();
+    const stories = state.stories;
+    let total = 0;
+    let done = 0;
+    let failed = 0;
+    let blocked = 0;
+    const storyStatuses = [];
+    for (const [key, story] of Object.entries(stories)) {
+      total++;
+      if (story.status === "done") done++;
+      else if (story.status === "failed") failed++;
+      else if (story.status === "blocked") blocked++;
+      storyStatuses.push({ key, status: story.status });
+    }
+    const sprintPercent = total > 0 ? Math.round(done / total * 100) : 0;
+    const { epicsTotal, epicsDone } = computeEpicProgress(stories);
+    const runSummary = buildRunSummary(state, effectiveNow);
+    const activeRun = state.run.active ? runSummary : null;
+    const lastRun = !state.run.active ? runSummary : null;
+    const failedDetails = buildFailedDetails(stories);
+    const actionItemsLabeled = buildActionItemsLabeled(state);
+    return ok2({
+      total,
+      done,
+      failed,
+      blocked,
+      inProgress: state.sprint.inProgress,
+      storyStatuses,
+      epicsTotal,
+      epicsDone,
+      sprintPercent,
+      activeRun,
+      lastRun,
+      failedDetails,
+      actionItemsLabeled
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return fail2(`Failed to generate report: ${msg}`);
+  }
+}
+
+// src/modules/sprint/timeout.ts
+import { readFileSync as readFileSync17, writeFileSync as writeFileSync10, existsSync as existsSync19, mkdirSync as mkdirSync6 } from "fs";
+import { execSync as execSync3 } from "child_process";
+import { join as join17 } from "path";
+var GIT_TIMEOUT_MS = 5e3;
+var DEFAULT_MAX_LINES = 100;
+function captureGitDiff() {
+  try {
+    const unstaged = execSync3("git diff --stat", {
+      timeout: GIT_TIMEOUT_MS,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"]
+    }).trim();
+    const staged = execSync3("git diff --cached --stat", {
+      timeout: GIT_TIMEOUT_MS,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"]
+    }).trim();
+    const parts = [];
+    if (unstaged) parts.push("Unstaged:\n" + unstaged);
+    if (staged) parts.push("Staged:\n" + staged);
+    if (parts.length === 0) {
+      return ok2("No changes detected");
+    }
+    return ok2(parts.join("\n\n"));
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return fail2(`Failed to capture git diff: ${msg}`);
+  }
+}
+function captureStateDelta(beforePath, afterPath) {
+  try {
+    if (!existsSync19(beforePath)) {
+      return fail2(`State snapshot not found: ${beforePath}`);
+    }
+    if (!existsSync19(afterPath)) {
+      return fail2(`Current state file not found: ${afterPath}`);
+    }
+    const beforeRaw = readFileSync17(beforePath, "utf-8");
+    const afterRaw = readFileSync17(afterPath, "utf-8");
+    const before = JSON.parse(beforeRaw);
+    const after = JSON.parse(afterRaw);
+    const beforeStories = before.stories ?? {};
+    const afterStories = after.stories ?? {};
+    const allKeys = /* @__PURE__ */ new Set([...Object.keys(beforeStories), ...Object.keys(afterStories)]);
+    const changes = [];
+    for (const key of allKeys) {
+      const beforeStatus = beforeStories[key]?.status ?? "(absent)";
+      const afterStatus = afterStories[key]?.status ?? "(absent)";
+      if (beforeStatus !== afterStatus) {
+        changes.push(`${key}: ${beforeStatus} \u2192 ${afterStatus}`);
+      }
+    }
+    if (changes.length === 0) {
+      return ok2("No state changes");
+    }
+    return ok2(changes.join("\n"));
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return fail2(`Failed to capture state delta: ${msg}`);
+  }
+}
+function capturePartialStderr(outputFile, maxLines = DEFAULT_MAX_LINES) {
+  try {
+    if (!existsSync19(outputFile)) {
+      return fail2(`Output file not found: ${outputFile}`);
+    }
+    const content = readFileSync17(outputFile, "utf-8");
+    const lines = content.split("\n");
+    if (lines.length > 0 && lines[lines.length - 1] === "") {
+      lines.pop();
+    }
+    const lastLines = lines.slice(-maxLines).join("\n");
+    return ok2(lastLines);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return fail2(`Failed to capture partial stderr: ${msg}`);
+  }
+}
+function formatReport(capture) {
+  const lines = [
+    `# Timeout Report: Iteration ${capture.iteration}`,
+    "",
+    `- **Story:** ${capture.storyKey}`,
+    `- **Duration:** ${capture.durationMinutes} minutes (timeout)`,
+    `- **Timestamp:** ${capture.timestamp}`,
+    "",
+    "## Git Changes",
+    "",
+    capture.gitDiff,
+    "",
+    "## State Delta",
+    "",
+    capture.stateDelta,
+    "",
+    "## Partial Output (last 100 lines)",
+    "",
+    "```",
+    capture.partialStderr,
+    "```",
+    ""
+  ];
+  return lines.join("\n");
+}
+function captureTimeoutReport(opts) {
+  try {
+    if (opts.iteration < 1 || !Number.isInteger(opts.iteration)) {
+      return fail2(`Invalid iteration number: ${opts.iteration}`);
+    }
+    if (opts.durationMinutes < 0) {
+      return fail2(`Invalid duration: ${opts.durationMinutes}`);
+    }
+    const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+    const gitResult = captureGitDiff();
+    const gitDiff = gitResult.success ? gitResult.data : `(unavailable: ${gitResult.error})`;
+    const statePath2 = join17(process.cwd(), "sprint-state.json");
+    const deltaResult = captureStateDelta(opts.stateSnapshotPath, statePath2);
+    const stateDelta = deltaResult.success ? deltaResult.data : `(unavailable: ${deltaResult.error})`;
+    const stderrResult = capturePartialStderr(opts.outputFile);
+    const partialStderr = stderrResult.success ? stderrResult.data : `(unavailable: ${stderrResult.error})`;
+    const capture = {
+      storyKey: opts.storyKey,
+      iteration: opts.iteration,
+      durationMinutes: opts.durationMinutes,
+      gitDiff,
+      stateDelta,
+      partialStderr,
+      timestamp
+    };
+    const reportDir = join17(process.cwd(), "ralph", "logs");
+    const safeStoryKey = opts.storyKey.replace(/[^a-zA-Z0-9._-]/g, "_");
+    const reportFileName = `timeout-report-${opts.iteration}-${safeStoryKey}.md`;
+    const reportPath = join17(reportDir, reportFileName);
+    if (!existsSync19(reportDir)) {
+      mkdirSync6(reportDir, { recursive: true });
+    }
+    const reportContent = formatReport(capture);
+    writeFileSync10(reportPath, reportContent, "utf-8");
+    return ok2({
+      filePath: reportPath,
+      capture
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return fail2(`Failed to capture timeout report: ${msg}`);
+  }
+}
+
+// src/modules/sprint/feedback.ts
+import { readFileSync as readFileSync18, writeFileSync as writeFileSync11 } from "fs";
+import { existsSync as existsSync20 } from "fs";
+import { join as join18 } from "path";
+
+// src/modules/sprint/index.ts
+function generateReport2() {
+  const stateResult = getSprintState();
+  if (!stateResult.success) {
+    return fail2(stateResult.error);
+  }
+  return generateReport(stateResult.data);
+}
+function getStoryDrillDown2(key) {
+  const stateResult = getSprintState();
+  if (!stateResult.success) {
+    return fail2(stateResult.error);
+  }
+  return getStoryDrillDown(stateResult.data, key);
+}
+function captureTimeoutReport2(opts) {
+  return captureTimeoutReport(opts);
+}
+
 // src/commands/status.ts
 function buildScopedEndpoints(endpoints, serviceName) {
   const encoded = encodeURIComponent(serviceName);
@@ -4518,9 +5151,13 @@ var DEFAULT_ENDPOINTS = {
   otel_http: "http://localhost:4318"
 };
 function registerStatusCommand(program) {
-  program.command("status").description("Show current harness status and health").option("--check-docker", "Check Docker stack health").option("--check", "Run health checks with pass/fail exit code").action(async (options, cmd) => {
+  program.command("status").description("Show current harness status and health").option("--check-docker", "Check Docker stack health").option("--check", "Run health checks with pass/fail exit code").option("--story <id>", "Show detailed status for a specific story").action(async (options, cmd) => {
     const opts = cmd.optsWithGlobals();
     const isJson = opts.json === true;
+    if (options.story) {
+      handleStoryDrillDown(options.story, isJson);
+      return;
+    }
     if (options.checkDocker) {
       await handleDockerCheck(isJson);
       return;
@@ -4552,6 +5189,7 @@ function handleFullStatus(isJson) {
     handleFullStatusJson(state);
     return;
   }
+  printSprintState();
   console.log(`Harness: codeharness v${state.harness_version}`);
   console.log(`Stack: ${state.stack ?? "unknown"}`);
   if (state.app_type) {
@@ -4688,10 +5326,12 @@ function handleFullStatusJson(state) {
   const scoped_endpoints = serviceName ? buildScopedEndpoints(endpoints, serviceName) : void 0;
   const beads = getBeadsData();
   const onboarding = getOnboardingProgressData();
+  const sprint = getSprintReportData();
   jsonOutput({
     version: state.harness_version,
     stack: state.stack,
     ...state.app_type ? { app_type: state.app_type } : {},
+    ...sprint ? { sprint } : {},
     enforcement: state.enforcement,
     docker,
     endpoints,
@@ -4883,6 +5523,116 @@ async function handleDockerCheck(isJson) {
     }
   }
 }
+function handleStoryDrillDown(storyId, isJson) {
+  const result = getStoryDrillDown2(storyId);
+  if (!result.success) {
+    if (isJson) {
+      jsonOutput({ status: "fail", message: result.error });
+    } else {
+      fail(result.error);
+    }
+    process.exitCode = 1;
+    return;
+  }
+  const d = result.data;
+  if (isJson) {
+    jsonOutput({
+      key: d.key,
+      status: d.status,
+      epic: d.epic,
+      attempts: d.attempts,
+      maxAttempts: d.maxAttempts,
+      lastAttempt: d.lastAttempt,
+      acResults: d.acDetails,
+      attemptHistory: d.attemptHistory,
+      proof: d.proofSummary
+    });
+    return;
+  }
+  console.log(`Story: ${d.key}`);
+  console.log(`Status: ${d.status} (attempt ${d.attempts}/${d.maxAttempts})`);
+  console.log(`Epic: ${d.epic}`);
+  console.log(`Last attempt: ${d.lastAttempt ?? "none"}`);
+  console.log("");
+  console.log("-- AC Results -------------------------------------------------------");
+  if (d.acDetails.length === 0) {
+    console.log("No AC results recorded");
+  } else {
+    for (const ac of d.acDetails) {
+      const tag = ac.verdict.toUpperCase();
+      console.log(`${ac.id}: [${tag}]`);
+      if (ac.verdict === "fail") {
+        if (ac.command) console.log(`  Command:  ${ac.command}`);
+        if (ac.expected) console.log(`  Expected: ${ac.expected}`);
+        if (ac.actual) console.log(`  Actual:   ${ac.actual}`);
+        if (ac.reason) console.log(`  Reason:   ${ac.reason}`);
+        if (ac.suggestedFix) console.log(`  Suggest:  ${ac.suggestedFix}`);
+      }
+    }
+  }
+  if (d.attemptHistory.length > 0) {
+    console.log("");
+    console.log("-- History ----------------------------------------------------------");
+    for (const attempt of d.attemptHistory) {
+      const acPart = attempt.failingAc ? ` (${attempt.failingAc})` : "";
+      console.log(`Attempt ${attempt.number}: ${attempt.outcome}${acPart}`);
+    }
+  }
+  if (d.proofSummary) {
+    console.log("");
+    const p = d.proofSummary;
+    const total = p.passCount + p.failCount + p.escalateCount + p.pendingCount;
+    console.log(
+      `Proof: ${p.path} (${p.passCount}/${total} pass, ${p.failCount} fail, ${p.escalateCount} escalate)`
+    );
+  }
+}
+function printSprintState() {
+  const reportResult = generateReport2();
+  if (!reportResult.success) {
+    console.log("Sprint state: unavailable");
+    return;
+  }
+  const r = reportResult.data;
+  console.log(`\u2500\u2500 Project State \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\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`);
+  console.log(`Sprint: ${r.done}/${r.total} done (${r.sprintPercent}%) | ${r.epicsDone}/${r.epicsTotal} epics complete`);
+  if (r.activeRun) {
+    console.log("");
+    console.log(`\u2500\u2500 Active Run \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\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`);
+    const currentStory = r.inProgress ?? "none";
+    console.log(`Status: running (iteration ${r.activeRun.iterations}, ${r.activeRun.duration} elapsed)`);
+    console.log(`Current: ${currentStory}`);
+    console.log(`Budget: $${r.activeRun.cost.toFixed(2)} spent`);
+  } else if (r.lastRun) {
+    console.log("");
+    console.log(`\u2500\u2500 Last Run Summary \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\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`);
+    console.log(`Duration: ${r.lastRun.duration} | Cost: $${r.lastRun.cost.toFixed(2)} | Iterations: ${r.lastRun.iterations}`);
+    console.log(`Completed:  ${r.lastRun.completed.length} stories${r.lastRun.completed.length > 0 ? ` (${r.lastRun.completed.join(", ")})` : ""}`);
+    if (r.failedDetails.length > 0) {
+      console.log(`Failed:     ${r.failedDetails.length} stor${r.failedDetails.length === 1 ? "y" : "ies"}`);
+      for (const fd of r.failedDetails) {
+        const acPart = fd.acNumber !== null ? `AC ${fd.acNumber}` : "unknown AC";
+        console.log(`  \u2514 ${fd.key}: ${acPart} \u2014 ${fd.errorLine} (attempt ${fd.attempts}/${fd.maxAttempts})`);
+      }
+    }
+    if (r.lastRun.blocked.length > 0) {
+      console.log(`Blocked:    ${r.lastRun.blocked.length} stories (retry-exhausted)`);
+    }
+  }
+  if (r.actionItemsLabeled.length > 0) {
+    console.log("");
+    console.log(`\u2500\u2500 Action Items \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\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`);
+    for (const la of r.actionItemsLabeled) {
+      console.log(`  [${la.label}] ${la.item.story}: ${la.item.description}`);
+    }
+  }
+  console.log("");
+}
+function getSprintReportData() {
+  const reportResult = generateReport2();
+  if (!reportResult.success) return null;
+  return reportResult.data;
+}
 function printBeadsSummary() {
   if (!isBeadsInitialized()) {
     console.log("Beads: not initialized");
@@ -4949,16 +5699,16 @@ function getBeadsData() {
 }
 
 // src/commands/onboard.ts
-import { join as join18 } from "path";
+import { join as join22 } from "path";
 
 // src/lib/scanner.ts
 import {
-  existsSync as existsSync17,
+  existsSync as existsSync21,
   readdirSync as readdirSync3,
-  readFileSync as readFileSync15,
+  readFileSync as readFileSync19,
   statSync as statSync2
 } from "fs";
-import { join as join15, relative as relative2 } from "path";
+import { join as join19, relative as relative2 } from "path";
 var SOURCE_EXTENSIONS2 = /* @__PURE__ */ new Set([".ts", ".js", ".py"]);
 var DEFAULT_MIN_MODULE_SIZE = 3;
 function getExtension2(filename) {
@@ -4983,7 +5733,7 @@ function countSourceFiles(dir) {
     for (const entry of entries) {
       if (isSkippedDir(entry)) continue;
       if (entry.startsWith(".") && current !== dir) continue;
-      const fullPath = join15(current, entry);
+      const fullPath = join19(current, entry);
       let stat;
       try {
         stat = statSync2(fullPath);
@@ -5006,7 +5756,7 @@ function countSourceFiles(dir) {
   return count;
 }
 function countModuleFiles(modulePath, rootDir) {
-  const fullModulePath = join15(rootDir, modulePath);
+  const fullModulePath = join19(rootDir, modulePath);
   let sourceFiles = 0;
   let testFiles = 0;
   function walk(current) {
@@ -5018,7 +5768,7 @@ function countModuleFiles(modulePath, rootDir) {
     }
     for (const entry of entries) {
       if (isSkippedDir(entry)) continue;
-      const fullPath = join15(current, entry);
+      const fullPath = join19(current, entry);
       let stat;
       try {
         stat = statSync2(fullPath);
@@ -5043,8 +5793,8 @@ function countModuleFiles(modulePath, rootDir) {
   return { sourceFiles, testFiles };
 }
 function detectArtifacts(dir) {
-  const bmadPath = join15(dir, "_bmad");
-  const hasBmad = existsSync17(bmadPath);
+  const bmadPath = join19(dir, "_bmad");
+  const hasBmad = existsSync21(bmadPath);
   return {
     hasBmad,
     bmadPath: hasBmad ? relative2(dir, bmadPath) || "_bmad" : null
@@ -5126,10 +5876,10 @@ function readPerFileCoverage(dir, format) {
   return null;
 }
 function readVitestPerFileCoverage(dir) {
-  const reportPath = join15(dir, "coverage", "coverage-summary.json");
-  if (!existsSync17(reportPath)) return null;
+  const reportPath = join19(dir, "coverage", "coverage-summary.json");
+  if (!existsSync21(reportPath)) return null;
   try {
-    const report = JSON.parse(readFileSync15(reportPath, "utf-8"));
+    const report = JSON.parse(readFileSync19(reportPath, "utf-8"));
     const result = /* @__PURE__ */ new Map();
     for (const [key, value] of Object.entries(report)) {
       if (key === "total") continue;
@@ -5141,10 +5891,10 @@ function readVitestPerFileCoverage(dir) {
   }
 }
 function readPythonPerFileCoverage(dir) {
-  const reportPath = join15(dir, "coverage.json");
-  if (!existsSync17(reportPath)) return null;
+  const reportPath = join19(dir, "coverage.json");
+  if (!existsSync21(reportPath)) return null;
   try {
-    const report = JSON.parse(readFileSync15(reportPath, "utf-8"));
+    const report = JSON.parse(readFileSync19(reportPath, "utf-8"));
     if (!report.files) return null;
     const result = /* @__PURE__ */ new Map();
     for (const [key, value] of Object.entries(report.files)) {
@@ -5160,13 +5910,13 @@ function auditDocumentation(dir) {
   const root = dir ?? process.cwd();
   const documents = [];
   for (const docName of AUDIT_DOCUMENTS) {
-    const docPath = join15(root, docName);
-    if (!existsSync17(docPath)) {
+    const docPath = join19(root, docName);
+    if (!existsSync21(docPath)) {
       documents.push({ name: docName, grade: "missing", path: null });
       continue;
     }
-    const srcDir = join15(root, "src");
-    const codeDir = existsSync17(srcDir) ? srcDir : root;
+    const srcDir = join19(root, "src");
+    const codeDir = existsSync21(srcDir) ? srcDir : root;
     const stale = isDocStale(docPath, codeDir);
     documents.push({
       name: docName,
@@ -5174,8 +5924,8 @@ function auditDocumentation(dir) {
       path: docName
     });
   }
-  const docsDir = join15(root, "docs");
-  if (existsSync17(docsDir)) {
+  const docsDir = join19(root, "docs");
+  if (existsSync21(docsDir)) {
     try {
       const stat = statSync2(docsDir);
       if (stat.isDirectory()) {
@@ -5187,10 +5937,10 @@ function auditDocumentation(dir) {
   } else {
     documents.push({ name: "docs/", grade: "missing", path: null });
   }
-  const indexPath = join15(root, "docs", "index.md");
-  if (existsSync17(indexPath)) {
-    const srcDir = join15(root, "src");
-    const indexCodeDir = existsSync17(srcDir) ? srcDir : root;
+  const indexPath = join19(root, "docs", "index.md");
+  if (existsSync21(indexPath)) {
+    const srcDir = join19(root, "src");
+    const indexCodeDir = existsSync21(srcDir) ? srcDir : root;
     const indexStale = isDocStale(indexPath, indexCodeDir);
     documents.push({
       name: "docs/index.md",
@@ -5207,8 +5957,8 @@ function auditDocumentation(dir) {
 
 // src/lib/epic-generator.ts
 import { createInterface } from "readline";
-import { existsSync as existsSync18, mkdirSync as mkdirSync6, writeFileSync as writeFileSync9 } from "fs";
-import { dirname as dirname5, join as join16 } from "path";
+import { existsSync as existsSync22, mkdirSync as mkdirSync7, writeFileSync as writeFileSync12 } from "fs";
+import { dirname as dirname6, join as join20 } from "path";
 var PRIORITY_BY_TYPE = {
   observability: 1,
   coverage: 2,
@@ -5246,8 +5996,8 @@ function generateOnboardingEpic(scan, coverage, audit, rootDir) {
     storyNum++;
   }
   for (const mod of scan.modules) {
-    const agentsPath = join16(root, mod.path, "AGENTS.md");
-    if (!existsSync18(agentsPath)) {
+    const agentsPath = join20(root, mod.path, "AGENTS.md");
+    if (!existsSync22(agentsPath)) {
       stories.push({
         key: `0.${storyNum}`,
         title: `Create ${mod.path}/AGENTS.md`,
@@ -5313,7 +6063,7 @@ function generateOnboardingEpic(scan, coverage, audit, rootDir) {
   };
 }
 function writeOnboardingEpic(epic, outputPath) {
-  mkdirSync6(dirname5(outputPath), { recursive: true });
+  mkdirSync7(dirname6(outputPath), { recursive: true });
   const lines = [];
   lines.push(`# ${epic.title}`);
   lines.push("");
@@ -5349,14 +6099,14 @@ function writeOnboardingEpic(epic, outputPath) {
   lines.push("");
   lines.push("Review and approve before execution.");
   lines.push("");
-  writeFileSync9(outputPath, lines.join("\n"), "utf-8");
+  writeFileSync12(outputPath, lines.join("\n"), "utf-8");
 }
 function formatEpicSummary(epic) {
   const { totalStories, coverageStories, docStories, verificationStories, observabilityStories } = epic.summary;
   return `Onboarding plan: ${totalStories} stories (${coverageStories} coverage, ${docStories} documentation, ${verificationStories} verification, ${observabilityStories} observability)`;
 }
 function promptApproval() {
-  return new Promise((resolve) => {
+  return new Promise((resolve2) => {
     let answered = false;
     const rl = createInterface({
       input: process.stdin,
@@ -5365,14 +6115,14 @@ function promptApproval() {
     rl.on("close", () => {
       if (!answered) {
         answered = true;
-        resolve(false);
+        resolve2(false);
       }
     });
     rl.question("Review the onboarding plan. Approve? [Y/n] ", (answer) => {
       answered = true;
       rl.close();
       const trimmed = answer.trim().toLowerCase();
-      resolve(trimmed === "" || trimmed === "y");
+      resolve2(trimmed === "" || trimmed === "y");
     });
   });
 }
@@ -5445,29 +6195,29 @@ function getGapIdFromTitle(title) {
 }
 
 // src/lib/scan-cache.ts
-import { existsSync as existsSync19, mkdirSync as mkdirSync7, readFileSync as readFileSync16, writeFileSync as writeFileSync10 } from "fs";
-import { join as join17 } from "path";
+import { existsSync as existsSync23, mkdirSync as mkdirSync8, readFileSync as readFileSync20, writeFileSync as writeFileSync13 } from "fs";
+import { join as join21 } from "path";
 var CACHE_DIR = ".harness";
 var CACHE_FILE = "last-onboard-scan.json";
 var DEFAULT_MAX_AGE_MS = 864e5;
 function saveScanCache(entry, dir) {
   try {
     const root = dir ?? process.cwd();
-    const cacheDir = join17(root, CACHE_DIR);
-    mkdirSync7(cacheDir, { recursive: true });
-    const cachePath = join17(cacheDir, CACHE_FILE);
-    writeFileSync10(cachePath, JSON.stringify(entry, null, 2), "utf-8");
+    const cacheDir = join21(root, CACHE_DIR);
+    mkdirSync8(cacheDir, { recursive: true });
+    const cachePath = join21(cacheDir, CACHE_FILE);
+    writeFileSync13(cachePath, JSON.stringify(entry, null, 2), "utf-8");
   } catch {
   }
 }
 function loadScanCache(dir) {
   const root = dir ?? process.cwd();
-  const cachePath = join17(root, CACHE_DIR, CACHE_FILE);
-  if (!existsSync19(cachePath)) {
+  const cachePath = join21(root, CACHE_DIR, CACHE_FILE);
+  if (!existsSync23(cachePath)) {
     return null;
   }
   try {
-    const raw = readFileSync16(cachePath, "utf-8");
+    const raw = readFileSync20(cachePath, "utf-8");
     return JSON.parse(raw);
   } catch {
     return null;
@@ -5640,7 +6390,7 @@ function registerOnboardCommand(program) {
     }
     coverage = lastCoverageResult ?? runCoverageAnalysis(scan);
     audit = lastAuditResult ?? runAudit();
-    const epicPath = join18(process.cwd(), "ralph", "onboarding-epic.md");
+    const epicPath = join22(process.cwd(), "ralph", "onboarding-epic.md");
     const epic = generateOnboardingEpic(scan, coverage, audit);
     mergeExtendedGaps(epic);
     if (!isFull) {
@@ -5713,7 +6463,7 @@ function registerOnboardCommand(program) {
       coverage,
       audit
     });
-    const epicPath = join18(process.cwd(), "ralph", "onboarding-epic.md");
+    const epicPath = join22(process.cwd(), "ralph", "onboarding-epic.md");
     const epic = generateOnboardingEpic(scan, coverage, audit);
     mergeExtendedGaps(epic);
     if (!isFull) {
@@ -5821,8 +6571,8 @@ function printEpicOutput(epic) {
 }
 
 // src/commands/teardown.ts
-import { existsSync as existsSync20, unlinkSync as unlinkSync2, readFileSync as readFileSync17, writeFileSync as writeFileSync11, rmSync } from "fs";
-import { join as join19 } from "path";
+import { existsSync as existsSync24, unlinkSync as unlinkSync2, readFileSync as readFileSync21, writeFileSync as writeFileSync14, rmSync } from "fs";
+import { join as join23 } from "path";
 function buildDefaultResult() {
   return {
     status: "ok",
@@ -5925,16 +6675,16 @@ function registerTeardownCommand(program) {
           info("Docker stack: not running, skipping");
         }
       }
-      const composeFilePath = join19(projectDir, composeFile);
-      if (existsSync20(composeFilePath)) {
+      const composeFilePath = join23(projectDir, composeFile);
+      if (existsSync24(composeFilePath)) {
         unlinkSync2(composeFilePath);
         result.removed.push(composeFile);
         if (!isJson) {
           ok(`Removed: ${composeFile}`);
         }
       }
-      const otelConfigPath = join19(projectDir, "otel-collector-config.yaml");
-      if (existsSync20(otelConfigPath)) {
+      const otelConfigPath = join23(projectDir, "otel-collector-config.yaml");
+      if (existsSync24(otelConfigPath)) {
         unlinkSync2(otelConfigPath);
         result.removed.push("otel-collector-config.yaml");
         if (!isJson) {
@@ -5944,8 +6694,8 @@ function registerTeardownCommand(program) {
     }
     let patchesRemoved = 0;
     for (const [patchName, relativePath] of Object.entries(PATCH_TARGETS)) {
-      const filePath = join19(projectDir, "_bmad", relativePath);
-      if (!existsSync20(filePath)) {
+      const filePath = join23(projectDir, "_bmad", relativePath);
+      if (!existsSync24(filePath)) {
         continue;
       }
       try {
@@ -5965,10 +6715,10 @@ function registerTeardownCommand(program) {
       }
     }
     if (state.otlp?.enabled && state.stack === "nodejs") {
-      const pkgPath = join19(projectDir, "package.json");
-      if (existsSync20(pkgPath)) {
+      const pkgPath = join23(projectDir, "package.json");
+      if (existsSync24(pkgPath)) {
         try {
-          const raw = readFileSync17(pkgPath, "utf-8");
+          const raw = readFileSync21(pkgPath, "utf-8");
           const pkg = JSON.parse(raw);
           const scripts = pkg["scripts"];
           if (scripts) {
@@ -5982,7 +6732,7 @@ function registerTeardownCommand(program) {
               for (const key of keysToRemove) {
                 delete scripts[key];
               }
-              writeFileSync11(pkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf-8");
+              writeFileSync14(pkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf-8");
               result.otlp_cleaned = true;
               if (!isJson) {
                 ok("OTLP: removed instrumented scripts from package.json");
@@ -6008,17 +6758,17 @@ function registerTeardownCommand(program) {
         }
       }
     }
-    const harnessDir = join19(projectDir, ".harness");
-    if (existsSync20(harnessDir)) {
+    const harnessDir = join23(projectDir, ".harness");
+    if (existsSync24(harnessDir)) {
       rmSync(harnessDir, { recursive: true, force: true });
       result.removed.push(".harness/");
       if (!isJson) {
         ok("Removed: .harness/");
       }
     }
-    const statePath = getStatePath(projectDir);
-    if (existsSync20(statePath)) {
-      unlinkSync2(statePath);
+    const statePath2 = getStatePath(projectDir);
+    if (existsSync24(statePath2)) {
+      unlinkSync2(statePath2);
       result.removed.push(".claude/codeharness.local.md");
       if (!isJson) {
         ok("Removed: .claude/codeharness.local.md");
@@ -6761,8 +7511,8 @@ function registerQueryCommand(program) {
 }
 
 // src/commands/retro-import.ts
-import { existsSync as existsSync21, readFileSync as readFileSync18 } from "fs";
-import { join as join20 } from "path";
+import { existsSync as existsSync25, readFileSync as readFileSync22 } from "fs";
+import { join as join24 } from "path";
 
 // src/lib/retro-parser.ts
 var KNOWN_TOOLS = ["showboat", "ralph", "beads", "bmad"];
@@ -6931,15 +7681,15 @@ function registerRetroImportCommand(program) {
       return;
     }
     const retroFile = `epic-${epicNum}-retrospective.md`;
-    const retroPath = join20(root, STORY_DIR2, retroFile);
-    if (!existsSync21(retroPath)) {
+    const retroPath = join24(root, STORY_DIR2, retroFile);
+    if (!existsSync25(retroPath)) {
       fail(`Retro file not found: ${retroFile}`, { json: isJson });
       process.exitCode = 1;
       return;
     }
     let content;
     try {
-      content = readFileSync18(retroPath, "utf-8");
+      content = readFileSync22(retroPath, "utf-8");
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
       fail(`Failed to read retro file: ${message}`, { json: isJson });
@@ -7207,8 +7957,8 @@ function registerGithubImportCommand(program) {
 
 // src/lib/verify-env.ts
 import { execFileSync as execFileSync7 } from "child_process";
-import { existsSync as existsSync22, mkdirSync as mkdirSync8, readdirSync as readdirSync4, readFileSync as readFileSync19, cpSync, rmSync as rmSync2, statSync as statSync3 } from "fs";
-import { join as join21, basename as basename3 } from "path";
+import { existsSync as existsSync26, mkdirSync as mkdirSync9, readdirSync as readdirSync4, readFileSync as readFileSync23, cpSync, rmSync as rmSync2, statSync as statSync3 } from "fs";
+import { join as join25, basename as basename3 } from "path";
 import { createHash } from "crypto";
 var IMAGE_TAG = "codeharness-verify";
 var STORY_DIR3 = "_bmad-output/implementation-artifacts";
@@ -7221,14 +7971,14 @@ function isValidStoryKey(storyKey) {
   return /^[a-zA-Z0-9_-]+$/.test(storyKey);
 }
 function computeDistHash(projectDir) {
-  const distDir = join21(projectDir, "dist");
-  if (!existsSync22(distDir)) {
+  const distDir = join25(projectDir, "dist");
+  if (!existsSync26(distDir)) {
     return null;
   }
   const hash = createHash("sha256");
   const files = collectFiles(distDir).sort();
   for (const file of files) {
-    const content = readFileSync19(file);
+    const content = readFileSync23(file);
     hash.update(file.slice(distDir.length));
     hash.update(content);
   }
@@ -7238,7 +7988,7 @@ function collectFiles(dir) {
   const results = [];
   const entries = readdirSync4(dir, { withFileTypes: true });
   for (const entry of entries) {
-    const fullPath = join21(dir, entry.name);
+    const fullPath = join25(dir, entry.name);
     if (entry.isDirectory()) {
       results.push(...collectFiles(fullPath));
     } else {
@@ -7310,13 +8060,13 @@ function buildNodeImage(projectDir) {
     throw new Error("npm pack produced no output \u2014 cannot determine tarball filename.");
   }
   const tarballName = basename3(lastLine);
-  const tarballPath = join21("/tmp", tarballName);
-  const buildContext = join21("/tmp", `codeharness-verify-build-${Date.now()}`);
-  mkdirSync8(buildContext, { recursive: true });
+  const tarballPath = join25("/tmp", tarballName);
+  const buildContext = join25("/tmp", `codeharness-verify-build-${Date.now()}`);
+  mkdirSync9(buildContext, { recursive: true });
   try {
-    cpSync(tarballPath, join21(buildContext, tarballName));
+    cpSync(tarballPath, join25(buildContext, tarballName));
     const dockerfileSrc = resolveDockerfileTemplate(projectDir);
-    cpSync(dockerfileSrc, join21(buildContext, "Dockerfile"));
+    cpSync(dockerfileSrc, join25(buildContext, "Dockerfile"));
     execFileSync7("docker", [
       "build",
       "-t",
@@ -7335,7 +8085,7 @@ function buildNodeImage(projectDir) {
   }
 }
 function buildPythonImage(projectDir) {
-  const distDir = join21(projectDir, "dist");
+  const distDir = join25(projectDir, "dist");
   const distFiles = readdirSync4(distDir).filter(
     (f) => f.endsWith(".tar.gz") || f.endsWith(".whl")
   );
@@ -7343,12 +8093,12 @@ function buildPythonImage(projectDir) {
     throw new Error("No distribution files found in dist/. Run your build command first (e.g., python -m build).");
   }
   const distFile = distFiles.filter((f) => f.endsWith(".tar.gz"))[0] ?? distFiles[0];
-  const buildContext = join21("/tmp", `codeharness-verify-build-${Date.now()}`);
-  mkdirSync8(buildContext, { recursive: true });
+  const buildContext = join25("/tmp", `codeharness-verify-build-${Date.now()}`);
+  mkdirSync9(buildContext, { recursive: true });
   try {
-    cpSync(join21(distDir, distFile), join21(buildContext, distFile));
+    cpSync(join25(distDir, distFile), join25(buildContext, distFile));
     const dockerfileSrc = resolveDockerfileTemplate(projectDir);
-    cpSync(dockerfileSrc, join21(buildContext, "Dockerfile"));
+    cpSync(dockerfileSrc, join25(buildContext, "Dockerfile"));
     execFileSync7("docker", [
       "build",
       "-t",
@@ -7370,25 +8120,25 @@ function prepareVerifyWorkspace(storyKey, projectDir) {
   if (!isValidStoryKey(storyKey)) {
     throw new Error(`Invalid story key: ${storyKey}. Keys must contain only alphanumeric characters, hyphens, and underscores.`);
   }
-  const storyFile = join21(root, STORY_DIR3, `${storyKey}.md`);
-  if (!existsSync22(storyFile)) {
+  const storyFile = join25(root, STORY_DIR3, `${storyKey}.md`);
+  if (!existsSync26(storyFile)) {
     throw new Error(`Story file not found: ${storyFile}`);
   }
   const workspace = `${TEMP_PREFIX}${storyKey}`;
-  if (existsSync22(workspace)) {
+  if (existsSync26(workspace)) {
     rmSync2(workspace, { recursive: true, force: true });
   }
-  mkdirSync8(workspace, { recursive: true });
-  cpSync(storyFile, join21(workspace, "story.md"));
-  const readmePath = join21(root, "README.md");
-  if (existsSync22(readmePath)) {
-    cpSync(readmePath, join21(workspace, "README.md"));
+  mkdirSync9(workspace, { recursive: true });
+  cpSync(storyFile, join25(workspace, "story.md"));
+  const readmePath = join25(root, "README.md");
+  if (existsSync26(readmePath)) {
+    cpSync(readmePath, join25(workspace, "README.md"));
   }
-  const docsDir = join21(root, "docs");
-  if (existsSync22(docsDir) && statSync3(docsDir).isDirectory()) {
-    cpSync(docsDir, join21(workspace, "docs"), { recursive: true });
+  const docsDir = join25(root, "docs");
+  if (existsSync26(docsDir) && statSync3(docsDir).isDirectory()) {
+    cpSync(docsDir, join25(workspace, "docs"), { recursive: true });
   }
-  mkdirSync8(join21(workspace, "verification"), { recursive: true });
+  mkdirSync9(join25(workspace, "verification"), { recursive: true });
   return workspace;
 }
 function checkVerifyEnv() {
@@ -7437,7 +8187,7 @@ function cleanupVerifyEnv(storyKey) {
   }
   const workspace = `${TEMP_PREFIX}${storyKey}`;
   const containerName = `codeharness-verify-${storyKey}`;
-  if (existsSync22(workspace)) {
+  if (existsSync26(workspace)) {
     rmSync2(workspace, { recursive: true, force: true });
   }
   try {
@@ -7456,11 +8206,11 @@ function cleanupVerifyEnv(storyKey) {
   }
 }
 function resolveDockerfileTemplate(projectDir) {
-  const local = join21(projectDir, "templates", "Dockerfile.verify");
-  if (existsSync22(local)) return local;
+  const local = join25(projectDir, "templates", "Dockerfile.verify");
+  if (existsSync26(local)) return local;
   const pkgDir = new URL("../../", import.meta.url).pathname;
-  const pkg = join21(pkgDir, "templates", "Dockerfile.verify");
-  if (existsSync22(pkg)) return pkg;
+  const pkg = join25(pkgDir, "templates", "Dockerfile.verify");
+  if (existsSync26(pkg)) return pkg;
   throw new Error("Dockerfile.verify not found. Ensure templates/Dockerfile.verify exists in the project or installed package.");
 }
 function dockerImageExists(tag) {
@@ -7606,26 +8356,26 @@ function registerVerifyEnvCommand(program) {
 }
 
 // src/commands/retry.ts
-import { join as join23 } from "path";
+import { join as join27 } from "path";
 
 // src/lib/retry-state.ts
-import { existsSync as existsSync23, readFileSync as readFileSync20, writeFileSync as writeFileSync12 } from "fs";
-import { join as join22 } from "path";
+import { existsSync as existsSync27, readFileSync as readFileSync24, writeFileSync as writeFileSync15 } from "fs";
+import { join as join26 } from "path";
 var RETRIES_FILE = ".story_retries";
 var FLAGGED_FILE = ".flagged_stories";
 var LINE_PATTERN = /^([^=]+)=(\d+)$/;
 function retriesPath(dir) {
-  return join22(dir, RETRIES_FILE);
+  return join26(dir, RETRIES_FILE);
 }
 function flaggedPath(dir) {
-  return join22(dir, FLAGGED_FILE);
+  return join26(dir, FLAGGED_FILE);
 }
 function readRetries(dir) {
   const filePath = retriesPath(dir);
-  if (!existsSync23(filePath)) {
+  if (!existsSync27(filePath)) {
     return /* @__PURE__ */ new Map();
   }
-  const raw = readFileSync20(filePath, "utf-8");
+  const raw = readFileSync24(filePath, "utf-8");
   const result = /* @__PURE__ */ new Map();
   for (const line of raw.split("\n")) {
     const trimmed = line.trim();
@@ -7647,7 +8397,7 @@ function writeRetries(dir, retries) {
   for (const [key, count] of retries) {
     lines.push(`${key}=${count}`);
   }
-  writeFileSync12(filePath, lines.length > 0 ? lines.join("\n") + "\n" : "", "utf-8");
+  writeFileSync15(filePath, lines.length > 0 ? lines.join("\n") + "\n" : "", "utf-8");
 }
 function resetRetry(dir, storyKey) {
   if (storyKey) {
@@ -7662,15 +8412,15 @@ function resetRetry(dir, storyKey) {
 }
 function readFlaggedStories(dir) {
   const filePath = flaggedPath(dir);
-  if (!existsSync23(filePath)) {
+  if (!existsSync27(filePath)) {
     return [];
   }
-  const raw = readFileSync20(filePath, "utf-8");
+  const raw = readFileSync24(filePath, "utf-8");
   return raw.split("\n").map((l) => l.trim()).filter((l) => l !== "");
 }
 function writeFlaggedStories(dir, stories) {
   const filePath = flaggedPath(dir);
-  writeFileSync12(filePath, stories.length > 0 ? stories.join("\n") + "\n" : "", "utf-8");
+  writeFileSync15(filePath, stories.length > 0 ? stories.join("\n") + "\n" : "", "utf-8");
 }
 function removeFlaggedStory(dir, key) {
   const stories = readFlaggedStories(dir);
@@ -7690,7 +8440,7 @@ function registerRetryCommand(program) {
   program.command("retry").description("Manage retry state for stories").option("--reset", "Clear retry counters and flagged stories").option("--story <key>", "Target a specific story key (used with --reset or --status)").option("--status", "Show retry status for all stories").action((_options, cmd) => {
     const opts = cmd.optsWithGlobals();
     const isJson = opts.json === true;
-    const dir = join23(process.cwd(), RALPH_SUBDIR);
+    const dir = join27(process.cwd(), RALPH_SUBDIR);
     if (opts.story && !isValidStoryKey3(opts.story)) {
       if (isJson) {
         jsonOutput({ status: "fail", message: `Invalid story key: ${opts.story}` });
@@ -7763,8 +8513,53 @@ function handleStatus(dir, isJson, filterStory) {
   }
 }
 
+// src/commands/timeout-report.ts
+function registerTimeoutReportCommand(program) {
+  program.command("timeout-report").description("Capture diagnostic data from a timed-out iteration").requiredOption("--story <key>", "Story key").requiredOption("--iteration <n>", "Iteration number").requiredOption("--duration <minutes>", "Timeout duration in minutes").requiredOption("--output-file <path>", "Path to iteration output log").requiredOption("--state-snapshot <path>", "Path to pre-iteration state snapshot").action((options, cmd) => {
+    const opts = cmd.optsWithGlobals();
+    const isJson = opts.json === true;
+    const iteration = parseInt(options.iteration, 10);
+    const duration = parseInt(options.duration, 10);
+    if (isNaN(iteration) || isNaN(duration)) {
+      if (isJson) {
+        jsonOutput({ status: "fail", message: "iteration and duration must be numbers" });
+      } else {
+        fail("iteration and duration must be numbers");
+      }
+      process.exitCode = 1;
+      return;
+    }
+    const result = captureTimeoutReport2({
+      storyKey: options.story,
+      iteration,
+      durationMinutes: duration,
+      outputFile: options.outputFile,
+      stateSnapshotPath: options.stateSnapshot
+    });
+    if (!result.success) {
+      if (isJson) {
+        jsonOutput({ status: "fail", message: result.error });
+      } else {
+        fail(result.error);
+      }
+      process.exitCode = 1;
+      return;
+    }
+    if (isJson) {
+      jsonOutput({
+        status: "ok",
+        reportPath: result.data.filePath,
+        storyKey: result.data.capture.storyKey,
+        iteration: result.data.capture.iteration
+      });
+    } else {
+      ok(`Timeout report written: ${result.data.filePath}`);
+    }
+  });
+}
+
 // src/index.ts
-var VERSION = true ? "0.18.1" : "0.0.0-dev";
+var VERSION = true ? "0.19.2" : "0.0.0-dev";
 function createProgram() {
   const program = new Command();
   program.name("codeharness").description("Makes autonomous coding agents produce software that actually works").version(VERSION).option("--json", "Output in machine-readable JSON format");
@@ -7785,6 +8580,7 @@ function createProgram() {
   registerGithubImportCommand(program);
   registerVerifyEnvCommand(program);
   registerRetryCommand(program);
+  registerTimeoutReportCommand(program);
   return program;
 }
 if (!process.env["VITEST"]) {