@saadnvd1/agent-os 0.3.723 → 0.3.728

package/lib/loops/checkCriteria.ts

@@ -0,0 +1,114 @@
+import type {
+  Analysis,
+  Criterion,
+  CommandResult,
+  CriterionStatus,
+  Evidence,
+} from "./types";
+
+export interface Resolver {
+  // The run's checks all passed.
+  green: boolean;
+  commands: CommandResult[];
+  // Changed lines per file on the branch: [start, end] ranges in the new file.
+  hunks: Map<string, [number, number][]>;
+  ci: { name: string; state: string; sha?: string | null }[];
+  snapshotSha: string;
+}
+
+// "@@ -a,b +c,d @@" per file, from `git diff -U0`.
+export function parseHunks(diff: string): Map<string, [number, number][]> {
+  const out = new Map<string, [number, number][]>();
+  let file: string | null = null;
+  for (const line of diff.split("\n")) {
+    if (line.startsWith("+++ ")) {
+      file = line.startsWith("+++ b/") ? line.slice(6) : null;
+      if (file && !out.has(file)) out.set(file, []);
+    } else if (file && line.startsWith("@@")) {
+      const m = /\+(\d+)(?:,(\d+))?/.exec(line);
+      if (m) {
+        const start = Number(m[1]);
+        const len = m[2] === undefined ? 1 : Number(m[2]);
+        out.get(file)!.push([start, start + Math.max(len, 1) - 1]);
+      }
+    }
+  }
+  return out;
+}
+
+const lower = (s: string) => s.toLowerCase();
+
+// Does the citation point at something this run really has? The model
+// proposes; this decides.
+export function resolves(e: Evidence | undefined, r: Resolver): boolean {
+  if (!e || !r.green) return false;
+  const ref = e.ref.trim();
+  if (!ref) return false;
+  switch (e.kind) {
+    case "test": {
+      const tests = r.commands.filter((c) => c.name === "test");
+      if (!tests.length || tests.some((c) => c.exitCode !== 0)) return false;
+      const want = lower(ref);
+      return tests.some((c) =>
+        c.passed.some((p) => lower(p).includes(want) || want.includes(lower(p)))
+      );
+    }
+    case "typecheck":
+      return r.commands.some((c) => c.name === "typecheck" && c.exitCode === 0);
+    case "diff": {
+      const m = /^(.*?)(?::(\d+))?$/.exec(ref);
+      const file = m?.[1] ?? ref;
+      const ranges = r.hunks.get(file);
+      if (!ranges) return false;
+      if (!m?.[2]) return true;
+      const line = Number(m[2]);
+      return ranges.some(([a, b]) => line >= a && line <= b);
+    }
+    case "ci":
+      return r.ci.some(
+        (c) =>
+          lower(c.name) === lower(ref) &&
+          c.state === "success" &&
+          c.sha === r.snapshotSha
+      );
+  }
+}
+
+export interface Mark {
+  id: number;
+  status: CriterionStatus;
+  evidence: Evidence | null;
+  verified: boolean;
+}
+
+// The analyst's marks, checked. "met" with no resolving citation stays open
+// and is shown as unverified; a criterion the analyst didn't mention goes
+// back to open (met at one snapshot is not met at the next); waived stays.
+export function checkCriteria(
+  criteria: Pick<Criterion, "id" | "status">[],
+  analysis: Pick<Analysis, "criteria">,
+  r: Resolver
+): Mark[] {
+  const said = new Map(analysis.criteria.map((c) => [c.id, c]));
+  return criteria.map((c) => {
+    if (c.status === "waived")
+      return { id: c.id, status: "waived", evidence: null, verified: true };
+    const a = said.get(c.id);
+    if (!a) return { id: c.id, status: "open", evidence: null, verified: true };
+    if (a.status !== "met")
+      return {
+        id: c.id,
+        status: a.status,
+        evidence: a.evidence ?? null,
+        verified: true,
+      };
+    return resolves(a.evidence, r)
+      ? { id: c.id, status: "met", evidence: a.evidence!, verified: true }
+      : {
+          id: c.id,
+          status: "open",
+          evidence: a.evidence ?? null,
+          verified: false,
+        };
+  });
+}

package/lib/loops/compactEvidence.ts

@@ -0,0 +1,140 @@
+import { failureSignature, normalize } from "../orchestrator/loop-guard";
+import { redact } from "../models/secrets";
+import type { CommandResult } from "./types";
+
+const ANSI = /\x1b\[[0-9;]*[A-Za-z]/g;
+const FAILED_TEST = /^\s*(?:FAIL\s+|[×✗]\s+|not ok \d+ - )(.+)$/;
+const PASSED_TEST = /^\s*(?:[✓√]\s+|ok \d+ - |PASS\s+)(.+)$/;
+// tsc: "file.ts(12,3): error TS2322: ..." or "file.ts:12:3 - error TS2322: ..."
+const TS_ERROR = /^(.+?)(?:\((\d+),\d+\)|:(\d+):\d+)\s*[:-]\s*error\s+(TS\d+)/;
+
+const MAX_TYPE_ERRORS = 30;
+const EXCERPT_LINES = 30;
+export const EVIDENCE_CHARS = 6000;
+
+const clean = (s: string) => s.replace(ANSI, "");
+
+// A passed test line carries its timing and count; the name is what a
+// citation names.
+const nameOf = (s: string) =>
+  normalize(s)
+    .replace(/\(\d+ tests?[^)]*\)/, "")
+    .trim();
+
+export function typeErrorsOf(output: string): string[] {
+  const seen = new Set<string>();
+  for (const line of clean(output).split("\n")) {
+    const m = TS_ERROR.exec(line.trim());
+    if (m) seen.add(`${m[1]}:${m[2] ?? m[3]} ${m[4]}`);
+  }
+  return [...seen];
+}
+
+function excerptOf(lines: string[], firstFailure: number): string {
+  const at =
+    firstFailure >= 0
+      ? firstFailure
+      : Math.max(lines.length - EXCERPT_LINES / 2, 0);
+  const from = Math.max(at - 5, 0);
+  return lines.slice(from, from + EXCERPT_LINES).join("\n");
+}
+
+// What one command did, in a few hundred tokens: exit code, the tests that
+// passed and failed, the type errors (once each), and the lines around the
+// first failure. No model.
+export function compactCommand(input: {
+  name: CommandResult["name"];
+  command: string;
+  exitCode: number | null;
+  durationMs: number;
+  output: string;
+}): CommandResult {
+  const lines = clean(input.output).split("\n");
+  const passed = new Set<string>();
+  const failed = new Set<string>();
+  let first = -1;
+  lines.forEach((l, i) => {
+    const f = FAILED_TEST.exec(l)?.[1];
+    if (f) {
+      failed.add(nameOf(f));
+      if (first < 0) first = i;
+      return;
+    }
+    const p = PASSED_TEST.exec(l)?.[1];
+    if (p) passed.add(nameOf(p));
+  });
+  const errors = input.name === "typecheck" ? typeErrorsOf(input.output) : [];
+  if (input.name === "typecheck" && errors.length && first < 0)
+    first = lines.findIndex((l) => TS_ERROR.test(l.trim()));
+  if (first < 0 && input.exitCode !== 0)
+    first = lines.findIndex((l) => /\berror\b|\bfail/i.test(l));
+  return {
+    name: input.name,
+    command: input.command,
+    exitCode: input.exitCode,
+    durationMs: input.durationMs,
+    passed: [...passed].slice(0, 400),
+    failed: [...failed].slice(0, 100),
+    errors: errors.slice(0, MAX_TYPE_ERRORS),
+    excerpt: redact(input.exitCode === 0 ? "" : excerptOf(lines, first)),
+  };
+}
+
+// The signature a repeat is judged by: the same one the merge loop guard
+// uses for a failing CI log, over the failing commands' output.
+export function signatureOf(
+  results: CommandResult[],
+  output: Map<string, string>
+): string | null {
+  const failing = results.filter((r) => r.exitCode !== 0 && !r.skipped);
+  if (!failing.length) return null;
+  const parts = failing.map(
+    (r) =>
+      failureSignature(r.name, output.get(r.name) ?? r.excerpt) ??
+      (r.errors.length
+        ? `${r.name}: ${r.errors.slice(0, 5).join("; ")}`
+        : `${r.name}: exit ${r.exitCode}`)
+  );
+  return parts.join(" | ").slice(0, 500);
+}
+
+export function scoreOf(results: CommandResult[], met: number) {
+  return {
+    met,
+    failingTests: results
+      .filter((r) => r.name === "test")
+      .reduce((n, r) => n + r.failed.length, 0),
+    typeErrors: results
+      .filter((r) => r.name === "typecheck")
+      .reduce((n, r) => n + r.errors.length, 0),
+  };
+}
+
+// The text the analyst reads, capped.
+export function evidenceText(
+  results: CommandResult[],
+  ci: { name: string; state: string }[]
+): string {
+  const out: string[] = [];
+  for (const r of results) {
+    const head = r.skipped
+      ? `${r.name}: skipped (${r.skipped})`
+      : `${r.name} \`${r.command}\`: ${r.exitCode === 0 ? "passed" : `FAILED (exit ${r.exitCode})`} in ${Math.round(r.durationMs / 1000)}s`;
+    out.push(head);
+    if (r.passed.length)
+      out.push(
+        `  passed (${r.passed.length}): ${r.passed.slice(0, 40).join("; ")}`
+      );
+    if (r.failed.length)
+      out.push(`  failed (${r.failed.length}): ${r.failed.join("; ")}`);
+    if (r.errors.length)
+      out.push(`  type errors (${r.errors.length}): ${r.errors.join("; ")}`);
+    if (r.excerpt) out.push(`  around the first failure:\n${r.excerpt}`);
+  }
+  if (ci.length)
+    out.push(`CI: ${ci.map((c) => `${c.name} ${c.state}`).join(", ")}`);
+  const text = out.join("\n");
+  return text.length > EVIDENCE_CHARS
+    ? `${text.slice(0, EVIDENCE_CHARS)}\n… (cut)`
+    : text;
+}

package/lib/loops/controls.ts

@@ -0,0 +1,317 @@
+import { getProject } from "../projects";
+import { queueEventOnce } from "../orchestrator/events";
+import { resolveAsks, taskSubject } from "../orchestrator/asks";
+import { defaultDeps, type LoopDeps } from "./deps";
+import { callHook } from "./hooks";
+import { cycleInFlight, deliverCycle } from "./runCycle";
+import { screenInstruction } from "./screenInstruction";
+import { finishLoop } from "./stopLoop";
+import {
+  addCriteria,
+  criteriaOf,
+  cyclesOf,
+  editCriterion,
+  getCycle,
+  insertLoop,
+  latestLoopFor,
+  liveLoopFor,
+  moveCycle,
+  patchCycle,
+  removeCriterion,
+  reopenLoop,
+  setLimits,
+  setRunNow,
+  waiveCriterion,
+} from "./store";
+import {
+  CRITERION_SOURCES,
+  DEFAULT_LIMITS,
+  LIMIT_BOUNDS,
+  LoopError,
+  type CriterionDraft,
+  type Limits,
+  type LoopRow,
+  type LoopView,
+} from "./types";
+
+export const MAX_CRITERIA = 30;
+export const CRITERION_MAX = 400;
+export const INSTRUCTION_MAX = 8000;
+
+export function cleanCriteria(drafts: CriterionDraft[]): CriterionDraft[] {
+  const out = drafts
+    .map((d) => ({
+      text: String(d.text ?? "")
+        .replace(/\s+/g, " ")
+        .trim()
+        .slice(0, CRITERION_MAX),
+      source: CRITERION_SOURCES.includes(d.source as never) ? d.source : "user",
+      evidenceKind: d.evidenceKind ?? null,
+    }))
+    .filter((d) => d.text);
+  if (!out.length)
+    throw new LoopError("Add at least one acceptance criterion", 400);
+  if (out.length > MAX_CRITERIA)
+    throw new LoopError(`At most ${MAX_CRITERIA} criteria`, 400);
+  return out as CriterionDraft[];
+}
+
+// Limits inside their bounds; a value out of range is refused, not clamped.
+export function cleanLimits(
+  input: Partial<Limits> = {},
+  base: Limits = DEFAULT_LIMITS
+): Limits {
+  const out = { ...base };
+  for (const key of Object.keys(LIMIT_BOUNDS) as (keyof Limits)[]) {
+    const v = input[key];
+    if (v === undefined) continue;
+    const [lo, hi] = LIMIT_BOUNDS[key];
+    if (typeof v !== "number" || !Number.isFinite(v) || v < lo || v > hi)
+      throw new LoopError(`${key} must be between ${lo} and ${hi}`, 400);
+    out[key] = key === "maxCostUsd" ? v : Math.round(v);
+  }
+  return out;
+}
+
+const workspaceOf = (task: {
+  project_id: string | null;
+  workspace_id: string | null;
+}) =>
+  (task.project_id && getProject(task.project_id)?.workspace_id) ||
+  task.workspace_id ||
+  null;
+
+function runningTask(deps: LoopDeps, taskId: string) {
+  const task = deps.task(taskId);
+  if (!task) throw new LoopError("No such task", 404);
+  if (task.task_status !== "running")
+    throw new LoopError("The task isn't running", 409);
+  if (task.quick_of)
+    throw new LoopError("A quick change has no agent to loop with", 409);
+  if (task.host_id && task.host_id !== "local")
+    throw new LoopError(
+      "The task runs on another machine: start the loop there",
+      409
+    );
+  return task;
+}
+
+export async function startLoop(
+  taskId: string,
+  input: { criteria: CriterionDraft[]; limits?: Partial<Limits> },
+  deps: LoopDeps = defaultDeps
+): Promise<LoopView> {
+  const task = runningTask(deps, taskId);
+  if (liveLoopFor(taskId))
+    throw new LoopError("A loop is already running on this task", 409);
+  const criteria = cleanCriteria(input.criteria);
+  const limits = cleanLimits(input.limits);
+  // A loop with no checks is the coder's claims again.
+  const prepared = await deps.prepare(task).catch((e: Error) => {
+    throw new LoopError(`Can't read the task's repository: ${e.message}`, 409);
+  });
+  const commands = await deps.commands(prepared.repo, prepared.base);
+  if (!commands.test && !commands.typecheck)
+    throw new LoopError(
+      "The base branch has no test command in agentos.json: add one so the loop has evidence to judge by",
+      409
+    );
+  const workspaceId = workspaceOf(task);
+  const now = deps.now();
+  const loop = insertLoop({
+    sessionId: taskId,
+    workspaceId,
+    goal: (task.task_prompt ?? "").slice(0, 20_000),
+    limits,
+    costBaseUsd: 0,
+    now,
+  });
+  addCriteria(loop.id, criteria);
+  if (workspaceId) {
+    resolveAsks(workspaceId, taskSubject(taskId), "a new loop started");
+    queueEventOnce(
+      workspaceId,
+      `loop:${taskId}:${loop.id}:started`,
+      taskId,
+      `Loop started on ${task.name}: ${criteria.length} criteria, up to ${limits.maxCycles} cycles.`
+    );
+  }
+  callHook("onStart", loop);
+  return loopView(taskId, deps)!;
+}
+
+export function stopByUser(
+  taskId: string,
+  deps: LoopDeps = defaultDeps
+): LoopView {
+  const loop = liveLoopFor(taskId);
+  if (!loop) throw new LoopError("No loop is running on this task", 409);
+  const task = deps.task(taskId);
+  finishLoop(
+    loop,
+    { reason: "stopped", detail: "stopped by you" },
+    { taskName: task?.name ?? "the task", now: deps.now() }
+  );
+  return loopView(taskId, deps)!;
+}
+
+export interface EditInput {
+  limits?: Partial<Limits>;
+  // Added on top of the current limits.
+  extend?: { cycles?: number; costUsd?: number; minutes?: number };
+  addCriteria?: CriterionDraft[];
+  editCriteria?: { id: number; text: string }[];
+  removeCriteria?: number[];
+  waive?: number[];
+}
+
+// Limits, extensions and criteria, on a running loop or one stopped on a
+// limit (an extension that clears the limit runs it again).
+export function editLoop(
+  taskId: string,
+  input: EditInput,
+  by = "you",
+  deps: LoopDeps = defaultDeps
+): LoopView {
+  const loop = latestLoopFor(taskId);
+  if (!loop) throw new LoopError("This task has no loop", 404);
+  if (input.limits) setLimits(loop.id, cleanLimits(input.limits, loop));
+  if (input.extend) {
+    const e = input.extend;
+    const next = cleanLimits(
+      {
+        maxCycles: e.cycles ? loop.maxCycles + e.cycles : undefined,
+        maxCostUsd: e.costUsd ? loop.maxCostUsd + e.costUsd : undefined,
+        maxMinutes: e.minutes ? loop.maxMinutes + e.minutes : undefined,
+      },
+      loop
+    );
+    setLimits(loop.id, next);
+    if (loop.state === "stopped" && loop.stopReason?.startsWith("limit:"))
+      resume(loop, deps);
+  }
+  if (input.addCriteria?.length) {
+    const have = criteriaOf(loop.id).length;
+    const add = cleanCriteria(input.addCriteria);
+    if (have + add.length > MAX_CRITERIA)
+      throw new LoopError(`At most ${MAX_CRITERIA} criteria`, 400);
+    addCriteria(loop.id, add);
+  }
+  for (const c of input.editCriteria ?? []) {
+    const text = String(c.text ?? "")
+      .replace(/\s+/g, " ")
+      .trim()
+      .slice(0, CRITERION_MAX);
+    if (!text) throw new LoopError("A criterion can't be empty", 400);
+    if (!editCriterion(c.id, loop.id, text))
+      throw new LoopError("No such criterion", 404);
+  }
+  for (const id of input.removeCriteria ?? [])
+    if (!removeCriterion(id, loop.id))
+      throw new LoopError("No such criterion", 404);
+  for (const id of input.waive ?? [])
+    if (!waiveCriterion(id, loop.id, by))
+      throw new LoopError("No such criterion", 404);
+  if (input.removeCriteria?.length && !criteriaOf(loop.id).length)
+    throw new LoopError("A loop needs at least one criterion", 400);
+  return loopView(taskId, deps)!;
+}
+
+function resume(loop: LoopRow, deps: LoopDeps): void {
+  const task = deps.task(loop.sessionId);
+  if (!task || task.task_status !== "running")
+    throw new LoopError("The task isn't running", 409);
+  if (liveLoopFor(loop.sessionId)) return;
+  if (!reopenLoop(loop.id)) return;
+  setRunNow(loop.id, true);
+  if (loop.workspaceId)
+    resolveAsks(
+      loop.workspaceId,
+      taskSubject(loop.sessionId),
+      "the loop was resumed"
+    );
+}
+
+// Run now: a cycle at the next tick, resuming a stopped loop (after criteria
+// were edited, say).
+export function runNow(taskId: string, deps: LoopDeps = defaultDeps): LoopView {
+  const loop = latestLoopFor(taskId);
+  if (!loop) throw new LoopError("This task has no loop", 404);
+  if (loop.state === "stopped") {
+    if (loop.stopReason === "done")
+      throw new LoopError("The loop is done", 409);
+    resume(loop, deps);
+  } else setRunNow(loop.id, true);
+  return loopView(taskId, deps)!;
+}
+
+export type NextAction =
+  | { action: "send"; instruction?: string }
+  | { action: "hold" }
+  | { action: "skip" };
+
+// What the person does with the instruction in its countdown: send it now
+// (edited or not), hold the countdown while they edit, or skip the cycle.
+export async function actOnNext(
+  taskId: string,
+  input: NextAction,
+  deps: LoopDeps = defaultDeps
+): Promise<LoopView> {
+  const loop = liveLoopFor(taskId);
+  if (!loop) throw new LoopError("No loop is running on this task", 409);
+  const task = deps.task(taskId);
+  const cycle = cyclesOf(loop.id, { limit: 1 })[0];
+  if (!task || !cycle || cycle.state !== "counting")
+    throw new LoopError("No instruction is waiting to be sent", 409);
+  if (input.action === "skip") {
+    moveCycle(loop.id, cycle.n, ["counting"], {
+      state: "skipped",
+      endedAt: deps.now(),
+    });
+  } else if (input.action === "hold") {
+    patchCycle(loop.id, cycle.n, { sendAt: null });
+  } else {
+    const edited = input.instruction?.trim();
+    if (edited !== undefined && !edited)
+      throw new LoopError("The instruction is empty", 400);
+    if (edited && edited.length > INSTRUCTION_MAX)
+      throw new LoopError("The instruction is too long", 400);
+    if (edited && edited !== cycle.instruction?.trim()) {
+      // The person may tell the coder what they like, but the loop still
+      // sends nothing that crosses a hard line on its own.
+      const refused = screenInstruction(edited);
+      if (refused)
+        throw new LoopError(
+          `Not sent: ${refused.why}. Send it to the coder yourself if you mean it.`,
+          409
+        );
+      patchCycle(loop.id, cycle.n, { instruction: edited, sender: "user" });
+    }
+    if (cycleInFlight(loop.id))
+      throw new LoopError("The cycle is still being prepared", 409);
+    await deliverCycle({ loop, task, facts: undefined, deps }, cycle.n);
+  }
+  return loopView(taskId, deps)!;
+}
+
+export function loopView(
+  taskId: string,
+  deps: LoopDeps = defaultDeps,
+  opts: { before?: number } = {}
+): LoopView | null {
+  const loop = latestLoopFor(taskId);
+  if (!loop) return null;
+  const task = deps.task(taskId);
+  const hold = loop.state === "running" && task ? deps.hold(loop, task) : null;
+  return {
+    loop,
+    hold: hold?.kind ?? null,
+    holdReason: hold?.reason ?? null,
+    spentUsd: deps.spent(loop),
+    elapsedMs: (loop.endedAt ?? deps.now()) - loop.startedAt,
+    criteria: criteriaOf(loop.id),
+    cycles: cyclesOf(loop.id, { before: opts.before, limit: 20 }),
+  };
+}
+
+export { getCycle };

package/lib/loops/decideStop.ts

@@ -0,0 +1,113 @@
+import type { AskKind } from "../orchestrator/ask-view";
+import type { Criterion, CycleRow, Limits, Score, StopReason } from "./types";
+
+export interface StopCheck {
+  limits: Limits;
+  startedAt: number;
+  // How many cycles have run, errors included; the length of `cycles` by default.
+  cycleCount?: number;
+  // Oldest first; the cycle just finished is the last.
+  cycles: Pick<CycleRow, "n" | "signature" | "score">[];
+  criteria: Pick<Criterion, "status">[];
+  // The latest cycle's checks all passed.
+  green: boolean;
+  spentUsd: number;
+  now: number;
+  userStop?: boolean;
+  // The analyst's blocker, a BLOCKED: line, a coder waiting on input, an
+  // open ask or a refused instruction: the words for the reader.
+  blocked?: string | null;
+}
+
+export interface Stop {
+  reason: StopReason;
+  detail: string;
+  // The ask a refused instruction raises, when it crossed a hard line.
+  askKind?: AskKind;
+}
+
+const usd = (n: number) => `$${n.toFixed(2)}`;
+
+// Strictly better: more criteria met, then fewer failing tests, then
+// fewer type errors.
+export function better(a: Score, b: Score): boolean {
+  if (a.met !== b.met) return a.met > b.met;
+  if (a.failingTests !== b.failingTests) return a.failingTests < b.failingTests;
+  return a.typeErrors < b.typeErrors;
+}
+
+function repeated(cycles: StopCheck["cycles"], n: number): string | null {
+  if (cycles.length < n) return null;
+  const last = cycles.slice(-n);
+  const sig = last[0].signature;
+  return sig && last.every((c) => c.signature === sig) ? sig : null;
+}
+
+// None of the last `n` cycles beat the best before it. A cycle with no
+// change scores the same as the one before, so it counts too.
+function stalled(cycles: StopCheck["cycles"], n: number): boolean {
+  if (cycles.length < n + 1) return false;
+  const scored = cycles.map((c) => c.score);
+  if (scored.some((s) => !s)) return false;
+  const all = scored as Score[];
+  let best = all[0];
+  for (const s of all.slice(1, all.length - n)) if (better(s, best)) best = s;
+  for (const s of all.slice(all.length - n)) {
+    if (better(s, best)) return false;
+  }
+  return true;
+}
+
+// The limits alone: checked on every tick, and they stop the next send,
+// never a turn that is running.
+export function limitStop(
+  c: Pick<StopCheck, "limits" | "startedAt" | "spentUsd" | "now"> & {
+    cycleCount: number;
+  }
+): Stop | null {
+  const l = c.limits;
+  if (c.cycleCount >= l.maxCycles)
+    return {
+      reason: "limit:cycles",
+      detail: `${c.cycleCount} of ${l.maxCycles} cycles used`,
+    };
+  if (c.spentUsd >= l.maxCostUsd)
+    return {
+      reason: "limit:cost",
+      detail: `${usd(c.spentUsd)} spent of the ${usd(l.maxCostUsd)} cap`,
+    };
+  const minutes = (c.now - c.startedAt) / 60_000;
+  if (minutes >= l.maxMinutes)
+    return {
+      reason: "limit:time",
+      detail: `${Math.round(minutes)} of ${l.maxMinutes} minutes used`,
+    };
+  return null;
+}
+
+// One pure decision at a cycle boundary. First match wins: the user, a
+// blocker, done, the same failure again, no progress, then the limits.
+export function decideStop(c: StopCheck): Stop | null {
+  if (c.userStop) return { reason: "stopped", detail: "stopped by you" };
+  if (c.blocked) return { reason: "blocked", detail: c.blocked };
+  const open = c.criteria.filter(
+    (k) => k.status !== "met" && k.status !== "waived"
+  );
+  if (c.criteria.length && !open.length && c.green)
+    return {
+      reason: "done",
+      detail: `all ${c.criteria.length} criteria met, checks green`,
+    };
+  const sig = repeated(c.cycles, c.limits.repeatCycles);
+  if (sig)
+    return {
+      reason: "repeat",
+      detail: `the same failure on ${c.limits.repeatCycles} cycles in a row: ${sig.slice(0, 200)}`,
+    };
+  if (stalled(c.cycles, c.limits.stallCycles))
+    return {
+      reason: "no_progress",
+      detail: `no improvement in ${c.limits.stallCycles} cycles`,
+    };
+  return limitStop({ ...c, cycleCount: c.cycleCount ?? c.cycles.length });
+}