infinity-harness 2.0.0

package/src/goalState.ts

@@ -0,0 +1,338 @@
+import { appendFile, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import {
+  GOAL_LOOP_STATE_SCHEMA_VERSION,
+  type GoalIterationState,
+  type GoalLoopState,
+  type GoalLoopTraceEvent,
+  validateGoalLoopState,
+} from "./goalLoop.ts";
+import { type GoalSpecification, validateGoalSpecification } from "./goalSpec.ts";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+declare const require: any;
+
+export const GOAL_STATE_FILE = "GOAL_STATE.json";
+export const GOAL_TRACE_FILE = "GOAL_TRACE.jsonl";
+export const GOAL_RESULT_FILE = "GOAL_RESULT.md";
+export const GOAL_SPEC_FILE = "GOAL_SPEC.json";
+
+export const CANONICAL_GOAL_SPEC_DIR = "harness/goals";
+export const CANONICAL_GOAL_SPEC_FILE = "GOAL_SPEC.json";
+
+export function canonicalGoalSpecPath(projectDir = process.cwd()): string {
+  return resolve(projectDir, CANONICAL_GOAL_SPEC_DIR, CANONICAL_GOAL_SPEC_FILE);
+}
+
+function writeCanonicalWithLockSync(projectDir: string, content: string): void {
+  const target = canonicalGoalSpecPath(projectDir);
+  // try proper-lockfile sync-ish via dynamic import fallback to plain write
+  try {
+    mkdirSync(dirname(target), { recursive: true });
+    // use proper-lockfile if available (async variant would need async; use sync file write with lock attempt)
+    // For sync canonical we rely on atomic tmp+rename and ignore lock if unavailable — async wrapper below handles lock
+    const tmp = `${target}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+    writeFileSync(tmp, content, "utf8");
+    // rename via node:fs renameSync equivalent (import already has rename async, but we use writeFileSync+rename via fs)
+    const { renameSync } = require("node:fs");
+    renameSync(tmp, target);
+  } catch {
+    // fallback simple write
+    try {
+      mkdirSync(dirname(target), { recursive: true });
+      writeFileSync(target, content, "utf8");
+    } catch {}
+  }
+}
+
+
+export interface GoalStateStoreOptions {
+  cwd?: string;
+  goalRunId: string;
+  goalRunDir?: string;
+}
+
+export interface GoalStateStorePaths {
+  goalRunId: string;
+  goalRunDir: string;
+  statePath: string;
+  tracePath: string;
+  resultPath: string;
+  goalSpecPath: string;
+  iterationsDir: string;
+}
+
+export class GoalStateStore {
+  readonly paths: GoalStateStorePaths;
+
+  constructor(options: GoalStateStoreOptions) {
+    const cwd = path.resolve(options.cwd ?? process.cwd());
+    const goalRunDir = options.goalRunDir ?? path.join(cwd, "tmp", "infinity-harness", "goals", options.goalRunId);
+    this.paths = {
+      goalRunId: options.goalRunId,
+      goalRunDir,
+      statePath: path.join(goalRunDir, GOAL_STATE_FILE),
+      tracePath: path.join(goalRunDir, GOAL_TRACE_FILE),
+      resultPath: path.join(goalRunDir, GOAL_RESULT_FILE),
+      goalSpecPath: path.join(goalRunDir, GOAL_SPEC_FILE),
+      iterationsDir: path.join(goalRunDir, "iterations"),
+    };
+  }
+
+  async ensureRunDir(): Promise<void> {
+    await mkdir(this.paths.iterationsDir, { recursive: true });
+  }
+
+  async saveState(state: GoalLoopState): Promise<void> {
+    validateGoalLoopState(state);
+    await this.ensureRunDir();
+    await atomicWriteFile(this.paths.statePath, `${JSON.stringify(state, null, 2)}\n`);
+  }
+
+  async loadState(): Promise<GoalLoopState> {
+    const text = await readFile(this.paths.statePath, "utf8");
+    return validateGoalLoopState(JSON.parse(text));
+  }
+
+  async saveGoalSpecification(spec: GoalSpecification): Promise<void> {
+    validateGoalSpecification(spec);
+    await this.ensureRunDir();
+    await atomicWriteFile(this.paths.goalSpecPath, `${JSON.stringify(spec, null, 2)}\n`);
+  }
+
+  /** Persist spec to runDir AND canonical harness/goals/GOAL_SPEC.json with proper-lockfile. */
+  async saveGoalSpecificationWithCanonical(
+    spec: GoalSpecification,
+    projectDir = process.cwd(),
+  ): Promise<void> {
+    await this.saveGoalSpecification(spec);
+    await this.saveCanonicalGoalSpecification(spec, projectDir);
+  }
+
+  async saveCanonicalGoalSpecification(spec: GoalSpecification, projectDir = process.cwd()): Promise<void> {
+    validateGoalSpecification(spec);
+    const content = `${JSON.stringify(spec, null, 2)}\n`;
+    const target = canonicalGoalSpecPath(projectDir);
+    // Use proper-lockfile async lock when available to serialize concurrent writers
+    let release: (() => Promise<void>) | null = null;
+    try {
+      const mod: any = await import("proper-lockfile");
+      const lockfile = mod.default ?? mod;
+      mkdirSync(dirname(target), { recursive: true });
+      if (!existsSync(target)) writeFileSync(target, "", "utf8");
+      release = (await (lockfile as any).lock(target, {
+        retries: { retries: 8, minTimeout: 20, maxTimeout: 80 },
+        stale: 10000,
+        realpath: false,
+      })) as any;
+    } catch {
+      release = null;
+    }
+    try {
+      const tmp = `${target}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+      await writeFile(tmp, content, "utf8");
+      await rename(tmp, target);
+    } finally {
+      if (release) {
+        try { await (release as any)(); } catch {}
+      }
+    }
+  }
+
+  async loadCanonicalGoalSpecification(projectDir = process.cwd()): Promise<GoalSpecification> {
+    const text = await readFile(canonicalGoalSpecPath(projectDir), "utf8");
+    return validateGoalSpecification(JSON.parse(text));
+  }
+
+  async tryLoadCanonicalGoalSpecification(projectDir = process.cwd()): Promise<GoalSpecification | undefined> {
+    try {
+      return await this.loadCanonicalGoalSpecification(projectDir);
+    } catch (error) {
+      if (isNodeErrnoException(error) && (error as any).code === "ENOENT") return undefined;
+      throw error;
+    }
+  }
+
+  async loadGoalSpecification(): Promise<GoalSpecification> {
+    const text = await readFile(this.paths.goalSpecPath, "utf8");
+    return validateGoalSpecification(JSON.parse(text));
+  }
+
+  async tryLoadGoalSpecification(): Promise<GoalSpecification | undefined> {
+    try {
+      return await this.loadGoalSpecification();
+    } catch (error) {
+      if (isNodeErrnoException(error) && error.code === "ENOENT") {
+        return undefined;
+      }
+      throw error;
+    }
+  }
+
+  async appendTrace(event: GoalLoopTraceEvent): Promise<void> {
+    await this.ensureRunDir();
+    await appendFile(this.paths.tracePath, `${JSON.stringify(event)}\n`, "utf8");
+  }
+
+  async appendNewTraceEvents(previousTraceLength: number, state: GoalLoopState): Promise<void> {
+    const events = state.trace.slice(Math.max(0, previousTraceLength));
+    for (const event of events) {
+      await this.appendTrace(event);
+    }
+  }
+
+  async initializeResultIfMissing(state: GoalLoopState): Promise<boolean> {
+    try {
+      await readFile(this.paths.resultPath, "utf8");
+      return false;
+    } catch (error) {
+      if (!isNodeErrnoException(error) || error.code !== "ENOENT") {
+        throw error;
+      }
+    }
+    await this.initializeResult(state);
+    return true;
+  }
+
+  async durableTraceLength(): Promise<number> {
+    try {
+      const text = await readFile(this.paths.tracePath, "utf8");
+      return text.split(/\r?\n/).filter((line) => line.trim()).length;
+    } catch (error) {
+      if (isNodeErrnoException(error) && error.code === "ENOENT") {
+        return 0;
+      }
+      throw error;
+    }
+  }
+
+  async initializeResult(state: GoalLoopState): Promise<void> {
+    validateGoalLoopState(state);
+    await this.ensureRunDir();
+    const lines = [
+      "# Pi Goal Task Result",
+      "",
+      `Run: ${state.goalRunId}`,
+      `Goal: ${state.goal}`,
+      `Started: ${state.startedAt}`,
+      `State: ${this.paths.statePath}`,
+      `Trace: ${this.paths.tracePath}`,
+      `Goal specification: ${this.paths.goalSpecPath}`,
+      "",
+      "## Safety limits",
+      "",
+      `- Minimum iterations before completion: ${state.limits.minIterations}`,
+      `- Max iterations: ${state.limits.maxIterations}`,
+      `- Run timeout: ${state.limits.timeoutMs}ms`,
+      `- Iteration timeout: ${state.limits.iterationTimeoutMs}ms`,
+      `- Reviewer timeout: ${state.limits.reviewerTimeoutMs}ms`,
+      "",
+    ];
+    await writeFile(this.paths.resultPath, `${lines.join("\n")}\n`, "utf8");
+  }
+
+  async appendIterationResult(iteration: GoalIterationState): Promise<void> {
+    await this.ensureRunDir();
+    const lines = [
+      "",
+      `## Iteration ${iteration.iteration}`,
+      "",
+      `Status: ${iteration.status}`,
+      `Started: ${iteration.startedAt}`,
+      `Updated: ${iteration.updatedAt}`,
+    ];
+    if (iteration.deadlineAt) {
+      lines.push(`Deadline: ${iteration.deadlineAt}`);
+    }
+    if (iteration.generatedTodo) {
+      lines.push("", "### Generated TODO", "", `Path: ${iteration.generatedTodo.todoPath}`);
+      if (iteration.generatedTodo.summary) {
+        lines.push(`Summary: ${iteration.generatedTodo.summary}`);
+      }
+    }
+    if (iteration.workerResult) {
+      lines.push(
+        "",
+        "### Worker result",
+        "",
+        `Status: ${iteration.workerResult.status}`,
+        `Summary: ${iteration.workerResult.summary}`,
+      );
+      if (iteration.workerResult.resultPath) {
+        lines.push(`Result path: ${iteration.workerResult.resultPath}`);
+      }
+      if (iteration.workerResult.todoPath) {
+        lines.push(`TODO path: ${iteration.workerResult.todoPath}`);
+      }
+      if (iteration.workerResult.taskResultPath) {
+        lines.push(`Task result path: ${iteration.workerResult.taskResultPath}`);
+      }
+      if (iteration.workerResult.workerProgressPath) {
+        lines.push(`Worker progress log: ${iteration.workerResult.workerProgressPath}`);
+      }
+      if (iteration.workerResult.error) {
+        lines.push(`Error: ${iteration.workerResult.error}`);
+      }
+    }
+    if (iteration.reviewerResult) {
+      lines.push(
+        "",
+        "### Reviewer result",
+        "",
+        `Decision: ${iteration.reviewerResult.decision}`,
+        `Complete: ${iteration.reviewerResult.complete ? "yes" : "no"}`,
+        `Summary: ${iteration.reviewerResult.summary}`,
+        `Rationale: ${iteration.reviewerResult.rationale}`,
+      );
+      if (iteration.reviewerResult.remainingWork.length > 0) {
+        lines.push("", "Remaining work:", ...iteration.reviewerResult.remainingWork.map((item) => `- ${item}`));
+      }
+    }
+    if (iteration.completion) {
+      lines.push(
+        "",
+        "### Completion",
+        "",
+        `Status: ${iteration.completion.status}`,
+        `Reason: ${iteration.completion.reason}`,
+      );
+    }
+    await appendFile(this.paths.resultPath, `${lines.join("\n")}\n`, "utf8");
+  }
+
+  async writeIterationSnapshot(iteration: GoalIterationState): Promise<string> {
+    const iterationDir = this.iterationDir(iteration.iteration);
+    await mkdir(iterationDir, { recursive: true });
+    const snapshotPath = path.join(iterationDir, "ITERATION_STATE.json");
+    await atomicWriteFile(snapshotPath, `${JSON.stringify(iteration, null, 2)}\n`);
+    return snapshotPath;
+  }
+
+  iterationDir(iteration: number): string {
+    return path.join(this.paths.iterationsDir, String(iteration).padStart(2, "0"));
+  }
+}
+
+export function goalStatePaths(options: GoalStateStoreOptions): GoalStateStorePaths {
+  return new GoalStateStore(options).paths;
+}
+
+async function atomicWriteFile(filePath: string, content: string): Promise<void> {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  const tmpPath = `${filePath}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+  await writeFile(tmpPath, content, "utf8");
+  await rename(tmpPath, filePath);
+}
+
+export function isGoalLoopState(value: unknown): value is GoalLoopState {
+  try {
+    return validateGoalLoopState(value).schemaVersion === GOAL_LOOP_STATE_SCHEMA_VERSION;
+  } catch {
+    return false;
+  }
+}
+
+function isNodeErrnoException(error: unknown): error is NodeJS.ErrnoException {
+  return error instanceof Error && "code" in error;
+}

package/src/loop.ts

@@ -0,0 +1,355 @@
+/**
+ * infinity-harness — the continuous run driver.
+ *
+ * This is what lets the harness work for hours or days without a human at the
+ * keyboard. After the agent goes idle, `decideNext` looks at the state on disk
+ * and answers one question: keep going, advance, wait, or stop.
+ *
+ * The hard part is not continuing — it is knowing when to *stop*. A loop that
+ * always continues will burn a weekend of tokens re-running a failing gate
+ * against an unchanged tree. Every guard here exists because that is the
+ * default failure mode of an autonomous loop paired with a weak model:
+ *
+ *   - a wall-clock budget, so a forgotten run ends on its own
+ *   - an iteration ceiling, independent of time
+ *   - a *no-progress* detector: if the gate fails repeatedly and the working
+ *     tree fingerprint has not moved, the agent is spinning, not working
+ *   - a retry budget per task, so one impossible task cannot consume the run
+ *   - an explicit human brake (`paused`, or a stop file) checked every tick
+ *
+ * The loop never silently gives up: every stop carries a reason the human
+ * reads when they come back.
+ */
+
+import { createHash } from "node:crypto";
+import { resolve } from "node:path";
+import type { HarnessConfig, Phase } from "./core/types.ts";
+import { loadConfig, saveConfig, isRetryExhausted, incrementPhaseRetry } from "./core/config.ts";
+import { loadFeatureList, computeProgress, nextActionableTask } from "./core/featureList.ts";
+import { runChecks } from "./core/gates.ts";
+import { advancePhase, isFinalPhase, nextPhase } from "./core/phases.ts";
+import { buildBrief, renderBrief } from "./core/brief.ts";
+import { harnessDir } from "./core/paths.ts";
+import { readJsonSafe, writeJsonAtomic, fileExists } from "./core/fsx.ts";
+import { run } from "./core/exec.ts";
+
+export const LOOP_STATE_FILE = "loop-state.json";
+export const STOP_FILE = "STOP";
+
+export const DEFAULT_MAX_ITERATIONS = 2000;
+export const DEFAULT_MAX_WALL_CLOCK_MS = 24 * 60 * 60 * 1000; // 24h
+/** Consecutive gate failures with an unchanged tree before we call it stuck. */
+export const DEFAULT_NO_PROGRESS_LIMIT = 3;
+
+export type LoopState = {
+  runId: string;
+  startedAt: string;
+  iterations: number;
+  lastFingerprint: string | null;
+  /** Consecutive failures where the tree fingerprint did not move. */
+  noProgressStreak: number;
+  lastPhase: string | null;
+  lastDecision: string | null;
+  stoppedAt: string | null;
+  stopReason: string | null;
+};
+
+export type LoopBudget = {
+  maxIterations: number;
+  maxWallClockMs: number;
+  noProgressLimit: number;
+};
+
+export type LoopDecision =
+  | { action: "continue"; message: string; reason: string }
+  | { action: "advanced"; toPhase: Phase; message: string; reason: string }
+  | { action: "stop"; reason: string; detail: string }
+  | { action: "wait"; reason: string; detail: string };
+
+export function loopStatePath(targetDir: string): string {
+  return resolve(harnessDir(targetDir), LOOP_STATE_FILE);
+}
+
+export function stopFilePath(targetDir: string): string {
+  return resolve(harnessDir(targetDir), STOP_FILE);
+}
+
+export function newLoopState(runId: string, now = new Date()): LoopState {
+  return {
+    runId,
+    startedAt: now.toISOString(),
+    iterations: 0,
+    lastFingerprint: null,
+    noProgressStreak: 0,
+    lastPhase: null,
+    lastDecision: null,
+    stoppedAt: null,
+    stopReason: null,
+  };
+}
+
+export function loadLoopState(targetDir: string, runId: string, now = new Date()): LoopState {
+  const stored = readJsonSafe<LoopState | null>(loopStatePath(targetDir), null);
+  if (stored && stored.runId === runId) return stored;
+  return newLoopState(runId, now);
+}
+
+export function saveLoopState(targetDir: string, state: LoopState): void {
+  try {
+    writeJsonAtomic(loopStatePath(targetDir), state);
+  } catch {
+    // Loop bookkeeping is not worth aborting a run over. Worst case the
+    // budget restarts, and the wall-clock guard still bounds it.
+  }
+}
+
+export function budgetFrom(config: HarnessConfig): LoopBudget {
+  const loop = (config.loop ?? {}) as Record<string, unknown>;
+  const num = (v: unknown, fallback: number): number =>
+    typeof v === "number" && Number.isFinite(v) && v > 0 ? v : fallback;
+  return {
+    maxIterations: num(loop.maxIterations, DEFAULT_MAX_ITERATIONS),
+    maxWallClockMs: num(loop.maxWallClockMs, DEFAULT_MAX_WALL_CLOCK_MS),
+    noProgressLimit: num(loop.noProgressLimit, DEFAULT_NO_PROGRESS_LIMIT),
+  };
+}
+
+/**
+ * A cheap fingerprint of the working tree plus the plan.
+ *
+ * Used only to answer "did anything change since the last failed gate?".
+ * `git status --porcelain` covers edits, and the plan revision covers task
+ * updates that leave no file trace. Outside a git repo we fall back to the
+ * plan alone, which still catches the common spin.
+ */
+export async function fingerprint(targetDir: string): Promise<string> {
+  const parts: string[] = [];
+  const r = await run("git status --porcelain", { cwd: targetDir, timeoutMs: 15_000 });
+  if (r.ok) parts.push(r.stdout);
+  const head = await run("git rev-parse HEAD", { cwd: targetDir, timeoutMs: 10_000 });
+  if (head.ok) parts.push(head.stdout);
+  try {
+    const { list } = loadFeatureList(targetDir);
+    parts.push(String(list.baseRevision));
+    parts.push(
+      (list.features ?? [])
+        .flatMap((f) => (f.tasks ?? []).map((t) => `${t.id}:${t.status}`))
+        .join(","),
+    );
+  } catch {
+    /* plan unreadable — the git half still fingerprints */
+  }
+  return createHash("sha256").update(parts.join("\u0000")).digest("hex").slice(0, 16);
+}
+
+export type DecideOptions = {
+  targetDir: string;
+  runId: string;
+  now?: Date;
+  /** Skip the gate run. Used by callers that already have a verdict. */
+  skipGate?: boolean;
+};
+
+/**
+ * Decide what happens after the agent settles.
+ *
+ * Order matters: human brakes first, then terminal conditions, then budgets,
+ * then the gate. A paused run must stop even if the gate would pass.
+ */
+export async function decideNext(options: DecideOptions): Promise<{ decision: LoopDecision; state: LoopState }> {
+  const { targetDir, runId } = options;
+  const now = options.now ?? new Date();
+  const state = loadLoopState(targetDir, runId, now);
+  state.iterations += 1;
+
+  const finish = (decision: LoopDecision): { decision: LoopDecision; state: LoopState } => {
+    state.lastDecision = decision.action;
+    if (decision.action === "stop") {
+      state.stoppedAt = now.toISOString();
+      state.stopReason = decision.reason;
+    }
+    saveLoopState(targetDir, state);
+    return { decision, state };
+  };
+
+  // -- human brakes ---------------------------------------------------------
+  if (fileExists(stopFilePath(targetDir))) {
+    return finish({
+      action: "stop",
+      reason: "stop-file",
+      detail: `harness/${STOP_FILE} exists — delete it to resume.`,
+    });
+  }
+
+  const { config, ok } = loadConfig(targetDir);
+  if (!ok) {
+    return finish({
+      action: "stop",
+      reason: "no-config",
+      detail: "harness/config.json is missing or unreadable.",
+    });
+  }
+  if (config.paused) {
+    return finish({
+      action: "wait",
+      reason: "paused",
+      detail: "The pipeline is paused. Unpause to continue.",
+    });
+  }
+
+  state.lastPhase = config.currentPhase;
+
+  // -- terminal conditions --------------------------------------------------
+  const { list } = loadFeatureList(targetDir);
+  const progress = computeProgress(list);
+  const allTasksDone = progress.tasksTotal > 0 && progress.tasksDone === progress.tasksTotal;
+
+  if (isFinalPhase(config.currentPhase, config.phases?.enabled) && allTasksDone) {
+    return finish({
+      action: "stop",
+      reason: "complete",
+      detail: `Pipeline complete: ${progress.tasksDone}/${progress.tasksTotal} tasks across ${progress.featuresTotal} feature(s).`,
+    });
+  }
+
+  const exhausted = isRetryExhausted(config);
+  if (exhausted.exhausted) {
+    return finish({
+      action: "stop",
+      reason: "retry-budget",
+      detail: `The ${exhausted.which} retry budget is exhausted. A human needs to look at this.`,
+    });
+  }
+
+  // -- budgets --------------------------------------------------------------
+  const budget = budgetFrom(config);
+  if (state.iterations > budget.maxIterations) {
+    return finish({
+      action: "stop",
+      reason: "max-iterations",
+      detail: `Reached the ${budget.maxIterations}-iteration ceiling for this run.`,
+    });
+  }
+  const elapsed = now.getTime() - new Date(state.startedAt).getTime();
+  if (elapsed > budget.maxWallClockMs) {
+    const hours = (budget.maxWallClockMs / 3_600_000).toFixed(1);
+    return finish({
+      action: "stop",
+      reason: "max-wall-clock",
+      detail: `Run exceeded its ${hours}h wall-clock budget.`,
+    });
+  }
+
+  // -- the gate -------------------------------------------------------------
+  const phase = config.currentPhase;
+  if (!phase) {
+    return finish({
+      action: "wait",
+      reason: "not-started",
+      detail: "No current phase. Initialise the harness before running the loop.",
+    });
+  }
+
+  const gate = options.skipGate ? null : await runChecks(targetDir, phase, { record: true });
+
+  if (gate && gate.overall) {
+    state.noProgressStreak = 0;
+    state.lastFingerprint = await fingerprint(targetDir);
+
+    const upcoming = nextPhase(phase, config.phases?.enabled);
+    if (upcoming === null) {
+      return finish({
+        action: "stop",
+        reason: "complete",
+        detail: `Gate passed on the final phase (${phase}).`,
+      });
+    }
+
+    const moved = await advancePhase(targetDir);
+    if (!moved.ok) {
+      return finish({
+        action: "wait",
+        reason: "advance-failed",
+        detail: moved.error ?? "phase advance failed",
+      });
+    }
+
+    const brief = await buildBrief(targetDir);
+    return finish({
+      action: "advanced",
+      toPhase: upcoming,
+      message: renderBrief(brief, moved.config ?? undefined),
+      reason: `gate passed on ${phase}`,
+    });
+  }
+
+  // Gate failed (or was skipped). Is the agent actually making progress?
+  //
+  // The first failure of a run has no baseline to compare against, so it is
+  // never counted as a stall: the streak starts only once we have seen the
+  // tree twice and it did not move. Capture the previous fingerprint before
+  // overwriting it, or the comparison is always against itself.
+  const previous = state.lastFingerprint;
+  const fp = await fingerprint(targetDir);
+  state.lastFingerprint = fp;
+
+  if (previous === null || previous !== fp) {
+    state.noProgressStreak = 0;
+  } else {
+    state.noProgressStreak += 1;
+  }
+
+  if (state.noProgressStreak >= budget.noProgressLimit) {
+    return finish({
+      action: "stop",
+      reason: "no-progress",
+      detail:
+        `The gate has failed ${state.noProgressStreak} times in a row with no change to the working tree ` +
+        `or the plan. The agent is looping without making progress` +
+        (gate ? `: ${gate.failures.join(", ")}` : "") +
+        `. Stopping so a human can intervene.`,
+    });
+  }
+
+  // Charge a phase retry so the configured budget still bounds the run even
+  // when the tree keeps changing but the gate never opens.
+  const fresh = loadConfig(targetDir);
+  if (fresh.ok) {
+    incrementPhaseRetry(fresh.config);
+    saveConfig(targetDir, fresh.config);
+  }
+
+  const brief = await buildBrief(targetDir);
+  const failures = gate
+    ? gate.checks
+        .filter((c) => !c.pass)
+        .map((c) => `  x ${c.name}: ${c.detail}`)
+        .join("\n")
+    : "(gate not run)";
+
+  const task = nextActionableTask(list);
+  const focus = task ? `\nCurrent task: ${task.compositeKey} — ${task.description}` : "";
+
+  return finish({
+    action: "continue",
+    reason: "gate failed",
+    message:
+      `The ${phase.toUpperCase()} gate did not pass. Fix exactly these, then stop talking — ` +
+      `the harness will re-validate automatically.\n\n${failures}${focus}\n\n` +
+      renderBrief(brief, fresh.ok ? fresh.config : undefined),
+  });
+}
+
+/** Human-readable one-liner for the status bar / notify. */
+export function describeDecision(d: LoopDecision): string {
+  switch (d.action) {
+    case "continue":
+      return `continuing — ${d.reason}`;
+    case "advanced":
+      return `advanced to ${d.toPhase}`;
+    case "wait":
+      return `waiting — ${d.detail}`;
+    case "stop":
+      return `stopped — ${d.detail}`;
+  }
+}