@mobrienv/autoloop-harness 0.8.0 → 0.9.2

package/dist/resume.d.ts

@@ -0,0 +1,61 @@
+import type { RunRecord } from "@mobrienv/autoloop-core/registry/types";
+import type { LoopContext, RunOptions, RunSummary } from "./types.js";
+export interface ResumeOptions {
+    /** Additional iterations to grant beyond the resume point. */
+    addIterations?: number;
+    /** Backend override (parsed `-b` spec), applied via reloadLoop. */
+    backendOverride?: Record<string, unknown>;
+    /** Log level override (e.g. "debug" for -v). */
+    logLevel?: string | null;
+    /**
+     * Main repo state dir holding the registry the record was read from. Used
+     * to anchor registryFile and worktree cleanup. When omitted it is derived
+     * from the record (project_dir + state dir name).
+     */
+    baseStateDir?: string;
+    /** Abort signal (CLI owns process signal handling). */
+    signal?: AbortSignal;
+    /** Structured-event listener. */
+    onEvent?: RunOptions["onEvent"];
+    /**
+     * Force every fan-out stage branch to relaunch rather than reuse a
+     * journaled `stage.branch.finish` record from an interrupted prior attempt.
+     */
+    noResume?: boolean;
+}
+export interface ResumeResult extends RunSummary {
+    resumedFromIteration: number;
+    newMaxIterations: number;
+}
+/**
+ * Compute the iteration to resume at, given the terminating stop reason and
+ * the last iteration recorded in the registry.
+ *
+ * - `max_iterations`: the registry iteration is the last *completed* one; the
+ *   blocked iteration is the next one (registryIteration + 1).
+ * - `backend_failed` / `backend_timeout`: the registry iteration is the one
+ *   that failed mid-flight; retry it (registryIteration).
+ * - `interrupted` / `stopped` (or anything else): scan the journal — if an
+ *   `iteration.finish` exists for registryIteration it completed, so resume at
+ *   the next one; otherwise it was in-flight, so retry it.
+ */
+export declare function determineResumeIteration(journalFile: string, runId: string, stopReason: string, registryIteration: number): number;
+/**
+ * Build a LoopContext that reuses an existing run's identity (run_id, journal,
+ * memory, working files, worktree) instead of generating fresh ones. Mirrors
+ * `buildLoopContext` but skips run-id generation and worktree creation; the
+ * one-time setup that resume needs (loading config, deriving paths, filling
+ * topology/backend/limits) is delegated to `reloadLoop`.
+ */
+export declare function buildResumeContext(record: RunRecord, options?: ResumeOptions): {
+    loop: LoopContext;
+    resumeIteration: number;
+    addIterations: number;
+};
+/**
+ * Resume a terminated run from where it left off. Validation (status, pid
+ * liveness, missing files) is the caller's responsibility (see the CLI
+ * command); this entry assumes the record is resumable and drives the same
+ * iteration loop `run()` uses.
+ */
+export declare function resume(record: RunRecord, options?: ResumeOptions): Promise<ResumeResult>;

package/dist/resume.js

@@ -0,0 +1,226 @@
+import { existsSync } from "node:fs";
+import { basename, join } from "node:path";
+import { jsonField } from "@mobrienv/autoloop-core";
+import * as config from "@mobrienv/autoloop-core/config";
+import { appendEvent, extractIteration, extractTopic, readRunLines, } from "@mobrienv/autoloop-core/journal";
+import { updateStatus as updateWorktreeStatus } from "@mobrienv/autoloop-core/worktree";
+import { ensureLayout, initStore, installRuntimeTools, reloadLoop, } from "./config-helpers.js";
+import { publishCapabilities } from "./control/dispatch.js";
+import { log } from "./display.js";
+import { buildControlAdapter, driveLoop } from "./index.js";
+import { registryStart } from "./registry-bridge.js";
+import { clearResumeRequest, clearSuspendState, readSuspendState, } from "./suspend-state.js";
+/**
+ * Compute the iteration to resume at, given the terminating stop reason and
+ * the last iteration recorded in the registry.
+ *
+ * - `max_iterations`: the registry iteration is the last *completed* one; the
+ *   blocked iteration is the next one (registryIteration + 1).
+ * - `backend_failed` / `backend_timeout`: the registry iteration is the one
+ *   that failed mid-flight; retry it (registryIteration).
+ * - `interrupted` / `stopped` (or anything else): scan the journal — if an
+ *   `iteration.finish` exists for registryIteration it completed, so resume at
+ *   the next one; otherwise it was in-flight, so retry it.
+ */
+export function determineResumeIteration(journalFile, runId, stopReason, registryIteration) {
+    if (stopReason === "max_iterations") {
+        return registryIteration + 1;
+    }
+    if (stopReason === "backend_failed" || stopReason === "backend_timeout") {
+        return registryIteration;
+    }
+    // interrupted / stopped / unknown: trust the journal.
+    const lines = readRunLines(journalFile, runId);
+    const finished = lines.some((line) => extractTopic(line) === "iteration.finish" &&
+        extractIteration(line) === String(registryIteration));
+    return finished ? registryIteration + 1 : registryIteration;
+}
+/**
+ * Build a LoopContext that reuses an existing run's identity (run_id, journal,
+ * memory, working files, worktree) instead of generating fresh ones. Mirrors
+ * `buildLoopContext` but skips run-id generation and worktree creation; the
+ * one-time setup that resume needs (loading config, deriving paths, filling
+ * topology/backend/limits) is delegated to `reloadLoop`.
+ */
+export function buildResumeContext(record, options = {}) {
+    const projectDir = record.project_dir;
+    if (!projectDir) {
+        throw new Error(`run ${record.run_id} has no project_dir; cannot resume`);
+    }
+    // findRunByPrefix reads the registry directly, so a resumable run always
+    // carries the real state_dir that registryStart wrote (.autoloop/ for shared
+    // and worktree modes, .autoloop/runs/<id>/ for run-scoped). Never guess it
+    // from the journal path — for run-scoped runs the journal lives at the
+    // top-level .autoloop/ while the state dir is .autoloop/runs/<id>/, so a
+    // dirname() guess would point at the wrong directory.
+    const stateDir = record.state_dir;
+    if (!stateDir) {
+        throw new Error(`run ${record.run_id} has no state_dir; cannot resume`);
+    }
+    const journalFile = record.journal_file;
+    const isolationMode = record.isolation_mode || "run-scoped";
+    const worktreeMode = isolationMode === "worktree";
+    const workDir = worktreeMode
+        ? record.worktree_path || record.work_dir
+        : record.work_dir;
+    // Recompute config-anchored paths exactly as buildLoopContext does, but
+    // rooted in this run's existing state dir rather than a freshly-created one.
+    const stateDirName = basename(stateDir);
+    const presetFile = record.preset_file || "";
+    const cfg = presetFile
+        ? config.loadProjectFromFile(presetFile, {
+            presetName: record.preset || basename(projectDir),
+            workDir,
+        })
+        : config.loadProject(projectDir, {
+            presetName: record.preset || basename(projectDir),
+            workDir,
+        });
+    const memoryRel = config.get(cfg, "core.memory_file", join(stateDirName, "memory.jsonl"));
+    const memoryFile = join(workDir, memoryRel);
+    // baseStateDir is the main repo's state dir (registry + worktree metadata
+    // live here). Prefer the caller-supplied path (the registry the record was
+    // read from); fall back to deriving it. In worktree mode the per-run journal
+    // lives under the worktree tree, so the main state dir is the project root's.
+    const baseStateDir = options.baseStateDir ||
+        (worktreeMode ? join(record.project_dir, stateDirName) : stateDir);
+    const registryFile = join(baseStateDir, "registry.jsonl");
+    const backendOverride = options.backendOverride || {};
+    const logLevel = options.logLevel || config.get(cfg, "core.log_level", "info");
+    // A durable suspend (written by a `suspend`-policy hook) carries its own
+    // recorded resume point — prefer it over the stop-reason heuristic, since
+    // it reflects exactly where the hook engine intended to resume rather than
+    // a best-effort guess from the journal.
+    const suspendState = readSuspendState(stateDir);
+    const resumeIteration = suspendState
+        ? suspendState.resumeIteration
+        : determineResumeIteration(journalFile, record.run_id, record.stop_reason, record.iteration);
+    // Budget is additive from the resume point. Default add-iterations to the
+    // run's original max_iterations (so a max_iterations stop, by default, grants
+    // another full run's worth of budget beyond what was completed).
+    const addIterations = options.addIterations && options.addIterations > 0
+        ? options.addIterations
+        : record.max_iterations ||
+            config.getInt(cfg, "event_loop.max_iterations", 3);
+    const newMaxIterations = resumeIteration - 1 + addIterations;
+    // The budget must survive reloadLoop (called at the start of every
+    // iteration), which re-reads event_loop.max_iterations from config. Layer it
+    // in as a run config override so each reload sees the additive budget rather
+    // than the static config value.
+    const configOverride = config.put({}, "event_loop.max_iterations", String(newMaxIterations));
+    const seed = {
+        paths: {
+            projectDir,
+            workDir,
+            stateDir,
+            journalFile,
+            memoryFile,
+            runMemoryFile: join(stateDir, "memory.jsonl"),
+            tasksFile: join(stateDir, "tasks.jsonl"),
+            registryFile,
+            toolPath: join(stateDir, "autoloops"),
+            piAdapterPath: join(stateDir, "pi-adapter"),
+            baseStateDir,
+            mainProjectDir: projectDir,
+            worktreeBranch: worktreeMode ? record.worktree_name : "",
+            worktreePath: worktreeMode ? record.worktree_path : "",
+            worktreeMetaDir: worktreeMode
+                ? join(baseStateDir, "worktrees", record.run_id)
+                : "",
+            configWorkDir: workDir,
+        },
+        runtime: {
+            runId: record.run_id,
+            selfCommand: "",
+            promptOverride: null,
+            backendOverride,
+            configOverride,
+            logLevel,
+            branchMode: false,
+            isolationMode,
+            noResume: options.noResume ?? false,
+        },
+        launch: {
+            preset: record.preset || basename(projectDir),
+            trigger: record.trigger || "cli",
+            createdAt: record.created_at || new Date().toISOString(),
+            parentRunId: record.parent_run_id || "",
+            presetFile,
+        },
+        profiles: {
+            active: [],
+            fragments: new Map(),
+            warnings: [],
+        },
+        store: {},
+    };
+    let loop = reloadLoop(seed);
+    // Override the iteration budget: reloadLoop reads it fresh from config; resume
+    // needs the additive budget from the resume point.
+    loop = {
+        ...loop,
+        limits: { ...loop.limits, maxIterations: newMaxIterations },
+    };
+    return { loop, resumeIteration, addIterations };
+}
+/**
+ * Resume a terminated run from where it left off. Validation (status, pid
+ * liveness, missing files) is the caller's responsibility (see the CLI
+ * command); this entry assumes the record is resumable and drives the same
+ * iteration loop `run()` uses.
+ */
+export async function resume(record, options = {}) {
+    const { loop: built, resumeIteration, addIterations, } = buildResumeContext(record, options);
+    let loop = built;
+    loop.onEvent = options.onEvent;
+    loop = initStore(loop);
+    ensureLayout(loop.paths.stateDir);
+    installRuntimeTools(loop);
+    // Append the resume marker before any iteration so the scratchpad and derive
+    // path see it. It's a system topic — routing ignores it.
+    appendEvent(loop.paths.journalFile, loop.runtime.runId, "", "loop.resume", jsonField("resumed_from_iteration", String(resumeIteration)) +
+        ", " +
+        jsonField("previous_stop_reason", record.stop_reason || "") +
+        ", " +
+        jsonField("add_iterations", String(addIterations)) +
+        ", " +
+        jsonField("new_max_iterations", String(loop.limits.maxIterations)));
+    // Registry: append a fresh record (status running, pid = this process). The
+    // registry is last-write-wins per run_id, so this transitions the run back to
+    // running exactly as the normal start path does.
+    registryStart(loop);
+    // Worktree mode: flip meta status back to running so the run isn't stuck as
+    // "failed" if it crashed mid-flight.
+    if (loop.paths.worktreeMetaDir && existsSync(loop.paths.worktreeMetaDir)) {
+        try {
+            updateWorktreeStatus(loop.paths.worktreeMetaDir, "running");
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    loop.controlAdapter = buildControlAdapter(loop);
+    if (loop.controlAdapter) {
+        publishCapabilities(loop.paths.stateDir, loop.controlAdapter);
+    }
+    // Clear durable suspend markers now that we're re-entering the loop at the
+    // recorded resume point — a stale suspend-state.json would otherwise make
+    // the next `run()` (or this resume, if invoked again) refuse to start.
+    clearSuspendState(loop.paths.stateDir);
+    clearResumeRequest(loop.paths.stateDir);
+    log(loop, "info", `resume run_id=${loop.runtime.runId} from_iteration=${resumeIteration} new_max_iterations=${loop.limits.maxIterations} (was: ${record.stop_reason || "unknown"})`);
+    const runOptions = {
+        workDir: loop.paths.workDir,
+        backendOverride: options.backendOverride,
+        logLevel: options.logLevel,
+        signal: options.signal,
+        onEvent: options.onEvent,
+    };
+    const summary = await driveLoop(loop, runOptions, resumeIteration);
+    return {
+        ...summary,
+        resumedFromIteration: resumeIteration,
+        newMaxIterations: loop.limits.maxIterations,
+    };
+}
+//# sourceMappingURL=resume.js.map

package/dist/resume.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resume.js","sourceRoot":"","sources":["../src/resume.ts"],"names":[],"mappings":"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"}

package/dist/scratchpad.js

@@ -20,15 +20,23 @@ function collectScratchpadEntries(lines) {
     const entries = [];
     for (const line of lines) {
         const event = decodeEvent(line);
-        if (!event ||
-            event.shape !== "fields" ||
-            event.topic !== "iteration.finish")
+        if (!event || event.shape !== "fields")
             continue;
-        entries.push({
-            iteration: event.iteration ?? "",
-            exitCode: event.fields.exit_code ?? "",
-            output: event.fields.output ?? "",
-        });
+        if (event.topic === "iteration.finish") {
+            entries.push({
+                kind: "iteration",
+                iteration: event.iteration ?? "",
+                exitCode: event.fields.exit_code ?? "",
+                output: event.fields.output ?? "",
+            });
+        }
+        else if (event.topic === "loop.resume") {
+            entries.push({
+                kind: "resume",
+                previousStopReason: event.fields.previous_stop_reason ?? "",
+                addIterations: event.fields.add_iterations ?? "",
+            });
+        }
     }
     return entries;
 }
@@ -36,6 +44,9 @@ function renderScratchpadEntries(entries) {
     return entries.map(scratchpadEntryText).join("");
 }
 function scratchpadEntryText(entry) {
+    if (entry.kind === "resume") {
+        return `${resumeMarkerText(entry)}\n\n`;
+    }
     return (heading(2, `Iteration ${entry.iteration}`) +
         "\n\n" +
         "exit_code=" +
@@ -44,7 +55,15 @@ function scratchpadEntryText(entry) {
         entry.output +
         "\n");
 }
+function resumeMarkerText(entry) {
+    const reason = entry.previousStopReason || "unknown";
+    const adding = entry.addIterations || "0";
+    return `--- resumed (was: ${reason}, adding ${adding} iterations) ---`;
+}
 function compactScratchpadItem(entry) {
+    if (entry.kind === "resume") {
+        return resumeMarkerText(entry);
+    }
     return ("Iteration " +
         entry.iteration +
         " exit_code=" +

package/dist/scratchpad.js.map

@@ -1 +1 @@
-{"version":3,"file":"scratchpad.js","sourceRoot":"","sources":["../src/scratchpad.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"scratchpad.js","sourceRoot":"","sources":["../src/scratchpad.ts"],"names":[],"mappings":"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"}

package/dist/stage.d.ts

@@ -0,0 +1,21 @@
+import type { BranchResult as FanoutBranchResult, FanoutStage } from "@mobrienv/autoloop-core/fanout";
+import type { IterationContext } from "./prompt.js";
+import type { LoopContext, RunSummary } from "./types.js";
+type IterateFn = (loop: LoopContext, iteration: number) => Promise<RunSummary>;
+/**
+ * Reconstruct previously-completed branch results for `stageId` from the
+ * journal's `stage.branch.finish` records (any prior attempt in this run,
+ * across iterations — a stage that was mid-flight when the run was
+ * interrupted leaves these records behind). The latest record per branch id
+ * wins. Empty when resume is disabled or nothing was journaled yet.
+ */
+export declare function loadResumedBranches(loop: LoopContext, stageId: string): Map<string, FanoutBranchResult>;
+/**
+ * Run a fan-out stage triggered by `emittedTopic`, reduce its branch results
+ * to a routing decision, journal it, and continue the loop at the outcome
+ * event. `stage.branch.finish` records (real launches only — resumed/
+ * budget-skipped branches are not re-journaled) let a later attempt resume
+ * this exact stage without relaunching branches that already finished.
+ */
+export declare function finishStageIteration(loop: LoopContext, iter: IterationContext, stage: FanoutStage, emittedTopic: string, iterate: IterateFn): Promise<RunSummary>;
+export {};

package/dist/stage.js

@@ -0,0 +1,131 @@
+// Wires fan-out `[[stage]]` execution into the iteration loop. Mirrors
+// `wave.ts`'s `continueAfterParallelJoin`: run the stage to a reduced routing
+// decision, journal it, emit the outcome event, and continue routing through
+// the SAME topology handoff every other event uses — the stage's `onPass`/
+// `onFail` are plain declared events, so the loop gains no special routing
+// path once the stage has finished.
+import { jsonField } from "@mobrienv/autoloop-core";
+import { appendEvent, appendHarnessEvent, extractField, extractTopic, readRunLines, } from "@mobrienv/autoloop-core/journal";
+import { runCostUsd } from "./display.js";
+import { expandStageBranches, runFanoutStage } from "./fanout-runner.js";
+import { buildStageBranchRunner } from "./wave/stage-branch-runner.js";
+/**
+ * Best-effort advisory cost-per-branch estimate, when a budget ceiling is set:
+ * spend-so-far divided by iterations completed so far (floored at a small
+ * constant so a still-cheap early run does not admit an unbounded wave).
+ * Command backends that never journal `backend.usage` report zero spend, so
+ * the ceiling is a no-op for them — documented as advisory/best-effort.
+ */
+function perBranchCostEstimate(loop, iteration) {
+    const spent = runCostUsd(loop);
+    if (spent <= 0)
+        return 0;
+    return Math.max(spent / Math.max(1, iteration), 0.01);
+}
+/**
+ * Which branches the budget ceiling admits this wave. When no ceiling is set
+ * (`maxCostUsd` is 0), every branch is admitted — width is bounded only by the
+ * concurrency semaphore. When a ceiling is set, branches are admitted up to
+ * what the remaining budget covers at the per-branch estimate; the rest are
+ * skipped (never launched) rather than launched and killed mid-flight —
+ * "stop admitting past the line, overshoot bounded by one wave".
+ */
+function admitByBudget(loop, iter, specs) {
+    const ceiling = loop.limits.maxCostUsd ?? 0;
+    if (ceiling <= 0)
+        return new Set(specs.map((s) => s.branchId));
+    const spent = runCostUsd(loop);
+    const remaining = Math.max(ceiling - spent, 0);
+    const perBranch = perBranchCostEstimate(loop, iter.iteration);
+    if (perBranch <= 0)
+        return new Set(specs.map((s) => s.branchId));
+    const admitted = Math.max(0, Math.floor(remaining / perBranch));
+    return new Set(specs.slice(0, admitted).map((s) => s.branchId));
+}
+/**
+ * Reconstruct previously-completed branch results for `stageId` from the
+ * journal's `stage.branch.finish` records (any prior attempt in this run,
+ * across iterations — a stage that was mid-flight when the run was
+ * interrupted leaves these records behind). The latest record per branch id
+ * wins. Empty when resume is disabled or nothing was journaled yet.
+ */
+export function loadResumedBranches(loop, stageId) {
+    const resumed = new Map();
+    if (loop.runtime.noResume)
+        return resumed;
+    const lines = readRunLines(loop.paths.journalFile, loop.runtime.runId);
+    for (const line of lines) {
+        if (extractTopic(line) !== "stage.branch.finish")
+            continue;
+        if (extractField(line, "stage_id") !== stageId)
+            continue;
+        const branchId = extractField(line, "branch_id");
+        if (!branchId)
+            continue;
+        const ok = extractField(line, "ok") === "true";
+        const rawData = extractField(line, "data");
+        let data;
+        if (ok && rawData) {
+            try {
+                data = JSON.parse(rawData);
+            }
+            catch {
+                data = undefined;
+            }
+        }
+        const error = extractField(line, "error");
+        resumed.set(branchId, {
+            branchId,
+            ok: ok && data !== undefined,
+            ...(data ? { data } : {}),
+            ...(error ? { error } : {}),
+        });
+    }
+    return resumed;
+}
+/**
+ * Run a fan-out stage triggered by `emittedTopic`, reduce its branch results
+ * to a routing decision, journal it, and continue the loop at the outcome
+ * event. `stage.branch.finish` records (real launches only — resumed/
+ * budget-skipped branches are not re-journaled) let a later attempt resume
+ * this exact stage without relaunching branches that already finished.
+ */
+export async function finishStageIteration(loop, iter, stage, emittedTopic, iterate) {
+    appendEvent(loop.paths.journalFile, loop.runtime.runId, String(iter.iteration), "stage.start", jsonField("stage_id", stage.id) +
+        ", " +
+        jsonField("trigger_topic", emittedTopic) +
+        ", " +
+        jsonField("branch_count", String(expandStageBranches(stage).length)));
+    const resumed = loadResumedBranches(loop, stage.id);
+    const specs = expandStageBranches(stage);
+    const toAdmit = specs.filter((s) => !resumed.has(s.branchId));
+    const admitted = admitByBudget(loop, iter, toAdmit);
+    const baseRunner = buildStageBranchRunner(loop, iter, stage.id);
+    const runner = async (spec) => {
+        const cached = resumed.get(spec.branchId);
+        if (cached)
+            return cached;
+        if (!admitted.has(spec.branchId)) {
+            return {
+                branchId: spec.branchId,
+                ok: false,
+                error: "budget: not admitted this wave",
+            };
+        }
+        return baseRunner(spec);
+    };
+    const concurrency = Math.max(1, loop.stage?.concurrency || 1);
+    const outcome = await runFanoutStage(stage, runner, concurrency);
+    appendEvent(loop.paths.journalFile, loop.runtime.runId, String(iter.iteration), "stage.join", jsonField("stage_id", stage.id) +
+        ", " +
+        jsonField("event", outcome.event) +
+        ", " +
+        jsonField("passed", String(outcome.passed)) +
+        ", " +
+        jsonField("reason", outcome.reason) +
+        ", " +
+        jsonField("resumed_branches", String(resumed.size)));
+    appendHarnessEvent(loop.paths.journalFile, loop.runtime.runId, String(iter.iteration), outcome.event, outcome.reason);
+    return iterate(loop, iter.iteration + 1);
+}
+//# sourceMappingURL=stage.js.map

package/dist/stage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stage.js","sourceRoot":"","sources":["../src/stage.ts"],"names":[],"mappings":"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"}

package/dist/stop.d.ts

@@ -1,8 +1,35 @@
-import type { LoopContext, RunSummary } from "./types.js";
+import type { LoopContext, RunSummary, StopReason } from "./types.js";
 export declare function stopMaxIterations(loop: LoopContext, iteration: number): RunSummary;
 export declare function stopBackendFailed(loop: LoopContext, iteration: number, output: string): RunSummary;
+/**
+ * Stop with a typed backend-error reason (rate_limited / quota_exhausted /
+ * auth_failed / transient_error) instead of a generic backend_failed, so the
+ * disposition reflects an availability/auth/quota issue rather than an agent
+ * failure — and downstream (retry ladder, quarantine) can key off it.
+ */
+export declare function stopBackendErrorClass(loop: LoopContext, iteration: number, reason: StopReason, output: string): RunSummary;
 export declare function stopBackendTimeout(loop: LoopContext, iteration: number, output: string): RunSummary;
 export declare function stopStalled(loop: LoopContext, completed: number, repeats: number): RunSummary;
 export declare function stopCostBudget(loop: LoopContext, completed: number, costUsd: number, maxCostUsd: number): RunSummary;
 export declare function stopMaxRuntime(loop: LoopContext, completed: number, elapsedMs: number, maxRuntimeMs: number, outputTail?: string): RunSummary;
-export declare function completeLoop(loop: LoopContext, iteration: number, reason: string): RunSummary;
+/**
+ * Fail-closed stop for an UNKNOWN metareview verdict under `on_error = hold`.
+ * The reviewer gave no trustworthy signal, so the loop halts and raises
+ * attention (failure.diagnostic + notify-class "failed") instead of silently
+ * advancing — a human decides whether to resume.
+ */
+export declare function stopReviewUnknown(loop: LoopContext, iteration: number, reasoning: string): RunSummary;
+/**
+ * Escalate a premature quit that exhausted its re-arm budget: stop with a
+ * distinct reason and raise attention rather than silently accepting a
+ * false-finish that left authorized work undone.
+ */
+export declare function stopPrematureQuit(loop: LoopContext, completed: number, reasons: string[]): RunSummary;
+/**
+ * Stop for a `suspend`-policy hook that fired and could not (or was not
+ * configured to) block in-process. Durable suspend state has already been
+ * written by the hooks engine (`writeSuspendState`); this only journals the
+ * typed stop reason and registry status so `autoloop resume` can pick it up.
+ */
+export declare function stopSuspended(loop: LoopContext, iteration: number, reason: string): RunSummary;
+export declare function completeLoop(loop: LoopContext, iteration: number, reason: StopReason): RunSummary;