@mobrienv/autoloop-harness 0.7.4 → 0.9.1

package/dist/file-mod-audit.js

@@ -0,0 +1,63 @@
+import { jsonField } from "@mobrienv/autoloop-core";
+import { appendEvent } from "@mobrienv/autoloop-core/journal";
+import { changedFiles, isGitRepo } from "./git-diff.js";
+/**
+ * Ralph-parity emit-boundary audit (opt-in via `event_loop.audit_file_mods`).
+ * Compares the working tree against HEAD after every iteration; if the
+ * single acting role (`iter.allowedRoles[0]`, the same convention used for
+ * per-role backend overrides) declares `disallowedTools`/`readOnly` and
+ * files changed during the iteration, journals + emits a typed
+ * `policy.file_modification_violation` event carrying the role and file
+ * list. Purely observational: the harness itself never stops or rejects
+ * completion on this result — it exists for parent orchestrators to react to.
+ *
+ * No-ops (returns `{ ran: false, ... }`) when the policy is disabled, and
+ * `{ ran: true, violated: false, ... }` outside a git work tree, when no
+ * files changed, when the acting role is ambiguous/unknown, or when the
+ * acting role has no file-mutation restriction.
+ */
+export function runFileModAudit(loop, iter, iteration) {
+    if (!loop.policy?.fileModAudit) {
+        return { ran: false, violated: false, violations: [] };
+    }
+    const workDir = loop.paths.workDir;
+    if (!isGitRepo(workDir)) {
+        return { ran: true, violated: false, violations: [] };
+    }
+    const files = changedFiles(workDir);
+    if (files.length === 0) {
+        return { ran: true, violated: false, violations: [] };
+    }
+    // Autoloop runs a single backend per iteration; allowedRoles[0] is the
+    // acting role for this turn (same convention prompt.ts uses to resolve
+    // per-role backend overrides). Ambiguous/empty routing is skipped rather
+    // than guessed, to avoid false-positive violations.
+    if (iter.allowedRoles.length !== 1) {
+        return { ran: true, violated: false, violations: [] };
+    }
+    const roleId = iter.allowedRoles[0];
+    const role = loop.topology.roles.find((r) => r.id === roleId);
+    if (!role) {
+        return { ran: true, violated: false, violations: [] };
+    }
+    const reason = role.readOnly
+        ? "read_only"
+        : (role.disallowedTools?.length ?? 0) > 0
+            ? "disallowed_tools"
+            : null;
+    if (!reason) {
+        return { ran: true, violated: false, violations: [] };
+    }
+    const violation = { role: roleId, files, reason };
+    appendEvent(loop.paths.journalFile, loop.runtime.runId, String(iteration), "policy.file_modification_violation", `${jsonField("role", roleId)}, ${jsonField("files", files.join(","))}, ${jsonField("reason", reason)}`);
+    loop.onEvent?.({
+        type: "policy.file_modification_violation",
+        runId: loop.runtime.runId,
+        iteration,
+        role: roleId,
+        files,
+        reason,
+    });
+    return { ran: true, violated: true, violations: [violation] };
+}
+//# sourceMappingURL=file-mod-audit.js.map

package/dist/file-mod-audit.js.map

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

package/dist/git-diff.d.ts

@@ -0,0 +1,19 @@
+export interface AddedLine {
+    file: string;
+    text: string;
+}
+export declare function isGitRepo(workDir: string): boolean;
+/**
+ * Lines introduced this run: added (`+`) lines from `git diff HEAD` plus the
+ * full contents of untracked, non-ignored files (which a diff against HEAD does
+ * not include). This is the surface a reward-hack would land on.
+ */
+export declare function collectAddedLines(workDir: string): AddedLine[];
+/**
+ * Files changed this run: tracked files differing from HEAD plus untracked,
+ * non-ignored files. Used to detect whether a given class of file (e.g. tests)
+ * was touched during the run that claims completion.
+ */
+export declare function changedFiles(workDir: string): string[];
+/** Dirty working tree entries from `git status --porcelain`. */
+export declare function porcelainStatus(workDir: string): string[];

package/dist/git-diff.js

@@ -0,0 +1,74 @@
+import { spawnSync } from "node:child_process";
+function git(workDir, args) {
+    const res = spawnSync("git", args, {
+        cwd: workDir,
+        encoding: "utf-8",
+        maxBuffer: 50 * 1024 * 1024,
+    });
+    return { ok: res.status === 0, stdout: res.stdout ?? "" };
+}
+export function isGitRepo(workDir) {
+    return git(workDir, ["rev-parse", "--is-inside-work-tree"]).ok;
+}
+/**
+ * Lines introduced this run: added (`+`) lines from `git diff HEAD` plus the
+ * full contents of untracked, non-ignored files (which a diff against HEAD does
+ * not include). This is the surface a reward-hack would land on.
+ */
+export function collectAddedLines(workDir) {
+    const lines = [];
+    const diff = git(workDir, ["diff", "--unified=0", "--no-color", "HEAD"]);
+    if (diff.ok) {
+        let file = "";
+        for (const raw of diff.stdout.split("\n")) {
+            if (raw.startsWith("+++ b/")) {
+                file = raw.slice(6);
+            }
+            else if (raw.startsWith("+++ ")) {
+                file = raw.slice(4);
+            }
+            else if (raw.startsWith("+") && !raw.startsWith("+++")) {
+                lines.push({ file, text: raw.slice(1) });
+            }
+        }
+    }
+    for (const file of untrackedFiles(workDir)) {
+        const content = spawnSync("cat", [file], {
+            cwd: workDir,
+            encoding: "utf-8",
+            maxBuffer: 20 * 1024 * 1024,
+        });
+        if (content.status === 0) {
+            for (const text of (content.stdout ?? "").split("\n")) {
+                lines.push({ file, text });
+            }
+        }
+    }
+    return lines;
+}
+function untrackedFiles(workDir) {
+    const res = git(workDir, ["ls-files", "--others", "--exclude-standard"]);
+    return res.ok ? res.stdout.split("\n").filter(Boolean) : [];
+}
+/**
+ * Files changed this run: tracked files differing from HEAD plus untracked,
+ * non-ignored files. Used to detect whether a given class of file (e.g. tests)
+ * was touched during the run that claims completion.
+ */
+export function changedFiles(workDir) {
+    const tracked = git(workDir, ["diff", "--name-only", "--no-color", "HEAD"]);
+    const files = new Set();
+    if (tracked.ok) {
+        for (const f of tracked.stdout.split("\n").filter(Boolean))
+            files.add(f);
+    }
+    for (const f of untrackedFiles(workDir))
+        files.add(f);
+    return [...files];
+}
+/** Dirty working tree entries from `git status --porcelain`. */
+export function porcelainStatus(workDir) {
+    const res = git(workDir, ["status", "--porcelain"]);
+    return res.ok ? res.stdout.split("\n").filter(Boolean) : [];
+}
+//# sourceMappingURL=git-diff.js.map

package/dist/git-diff.js.map

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

package/dist/guards.d.ts

@@ -0,0 +1,37 @@
+export interface StallCheck {
+    stalled: boolean;
+    repeats: number;
+}
+/**
+ * Detect a no-progress loop: `threshold` (or more) consecutive iterations
+ * whose backend output is byte-identical. A threshold of 0 disables the
+ * check. Empty outputs never count as a stall — backend failures and
+ * timeouts already have their own stop reasons.
+ */
+export declare function detectStall(runLines: string[], threshold: number): StallCheck;
+/**
+ * Epoch-ms start of the run, from the `created_at` field of the run's
+ * `loop.start` event. Null when absent or unparseable, in which case the
+ * runtime budget guard disables itself.
+ */
+export declare function loopStartMs(runLines: string[]): number | null;
+export interface RuntimeBudgetCheck {
+    exceeded: boolean;
+    elapsedMs: number;
+}
+/**
+ * Check elapsed wall-clock time (from the journaled `loop.start` event)
+ * against a runtime budget. A budget of 0 disables the check; so does a
+ * missing or unparseable start timestamp.
+ */
+export declare function checkRuntimeBudget(runLines: string[], maxRuntimeMs: number, nowMs?: number): RuntimeBudgetCheck;
+export interface CostBudgetCheck {
+    exceeded: boolean;
+    costUsd: number;
+}
+/**
+ * Check accumulated run cost (from `backend.usage` events) against a USD
+ * budget. A budget of 0 disables the check. Backends without usage telemetry
+ * report zero cost, so the budget never fires for them.
+ */
+export declare function checkCostBudget(runLines: string[], maxCostUsd: number): CostBudgetCheck;

package/dist/guards.js

@@ -0,0 +1,78 @@
+// Run-level guard checks evaluated between iterations.
+//
+// Both guards are journal-derived (no in-memory counters), so they survive
+// context reloads and apply uniformly to every continue path — routed events,
+// rejected emits, and plain continues alike.
+import { collectUsage, decodeEvent } from "@mobrienv/autoloop-core";
+/**
+ * Detect a no-progress loop: `threshold` (or more) consecutive iterations
+ * whose backend output is byte-identical. A threshold of 0 disables the
+ * check. Empty outputs never count as a stall — backend failures and
+ * timeouts already have their own stop reasons.
+ */
+export function detectStall(runLines, threshold) {
+    if (threshold <= 0)
+        return { stalled: false, repeats: 0 };
+    const outputs = [];
+    for (const line of runLines) {
+        const event = decodeEvent(line);
+        if (!event || event.shape !== "fields")
+            continue;
+        if (event.topic !== "iteration.finish")
+            continue;
+        outputs.push((event.fields.output ?? "").trim());
+    }
+    if (outputs.length === 0)
+        return { stalled: false, repeats: 0 };
+    const last = outputs[outputs.length - 1];
+    if (last === "")
+        return { stalled: false, repeats: 0 };
+    let repeats = 1;
+    for (let i = outputs.length - 2; i >= 0 && outputs[i] === last; i--) {
+        repeats++;
+    }
+    return { stalled: repeats >= threshold, repeats };
+}
+/**
+ * Epoch-ms start of the run, from the `created_at` field of the run's
+ * `loop.start` event. Null when absent or unparseable, in which case the
+ * runtime budget guard disables itself.
+ */
+export function loopStartMs(runLines) {
+    for (const line of runLines) {
+        const event = decodeEvent(line);
+        if (!event || event.shape !== "fields")
+            continue;
+        if (event.topic !== "loop.start")
+            continue;
+        const parsed = Date.parse(event.fields.created_at ?? "");
+        return Number.isNaN(parsed) ? null : parsed;
+    }
+    return null;
+}
+/**
+ * Check elapsed wall-clock time (from the journaled `loop.start` event)
+ * against a runtime budget. A budget of 0 disables the check; so does a
+ * missing or unparseable start timestamp.
+ */
+export function checkRuntimeBudget(runLines, maxRuntimeMs, nowMs = Date.now()) {
+    if (maxRuntimeMs <= 0)
+        return { exceeded: false, elapsedMs: 0 };
+    const startMs = loopStartMs(runLines);
+    if (startMs === null)
+        return { exceeded: false, elapsedMs: 0 };
+    const elapsedMs = nowMs - startMs;
+    return { exceeded: elapsedMs >= maxRuntimeMs, elapsedMs };
+}
+/**
+ * Check accumulated run cost (from `backend.usage` events) against a USD
+ * budget. A budget of 0 disables the check. Backends without usage telemetry
+ * report zero cost, so the budget never fires for them.
+ */
+export function checkCostBudget(runLines, maxCostUsd) {
+    if (maxCostUsd <= 0)
+        return { exceeded: false, costUsd: 0 };
+    const { totals } = collectUsage(runLines);
+    return { exceeded: totals.costUsd >= maxCostUsd, costUsd: totals.costUsd };
+}
+//# sourceMappingURL=guards.js.map

package/dist/guards.js.map

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

package/dist/hooks.d.ts

@@ -0,0 +1,78 @@
+import type { HookPhase } from "@mobrienv/autoloop-core/hooks-schema";
+import type { LoopContext, StopReason } from "./types.js";
+export interface HookEnv {
+    AUTOLOOP_PROJECT_DIR: string;
+    AUTOLOOP_RUN_ID: string;
+    AUTOLOOP_PRESET: string;
+    AUTOLOOP_TASKS_FILE: string;
+    AUTOLOOP_ITERATION?: string;
+    AUTOLOOP_GIT_SHA_BEFORE?: string;
+    AUTOLOOP_GIT_SHA_AFTER?: string;
+    /** Run stop reason, set on post_run (e.g. "completed" = success). */
+    AUTOLOOP_STOP_REASON?: string;
+}
+export declare function buildHookEnv(loop: LoopContext, extra?: {
+    iteration?: number;
+    gitShaBefore?: string;
+    gitShaAfter?: string;
+    stopReason?: StopReason;
+}): HookEnv;
+export declare function captureGitSha(cwd: string): string;
+/**
+ * Legacy single-hook entry point (`runHook`). Kept for backward compatibility
+ * with any external callers/tests; internally the engine runs hooks through
+ * `runPhaseHooks` which layers policy + mutation on top of this same spawn +
+ * journal behavior.
+ */
+export declare function runHook(loop: LoopContext, name: string, cmd: string, hookEnv: HookEnv, iteration?: string): void;
+/**
+ * Parse a mutation directive from hook stdout, given which kind of mutation
+ * this hook is configured for:
+ *
+ * - `mutate="prompt"`: a fenced block (`<<<AUTOLOOP_MUTATE>>> ... <<<END>>>`)
+ *   or a `{"prompt": "..."}` JSON line take precedence; otherwise the *entire*
+ *   trimmed stdout becomes the new prompt (so a hook can be as simple as
+ *   `echo "new prompt text"`).
+ * - `mutate="event"`: requires a JSON object with `topic` and/or `payload`
+ *   (there is no plain-text form — an emitted event is structured, not free
+ *   text).
+ *
+ * Empty/malformed stdout is not an error — it simply yields no mutation
+ * (returns null), since a hook may run for its side effects alone.
+ */
+export declare function parseMutationDirective(stdout: string, mutate: "prompt" | "event"): {
+    prompt?: string;
+    topic?: string;
+    payload?: string;
+} | null;
+export interface PhaseHookResult {
+    /** Mutated prompt, when a `mutate="prompt"` hook produced one (pre_iteration). */
+    mutatedPrompt?: string;
+    /** Mutated event, when a `mutate="event"` hook produced one (pre_emit). */
+    mutatedEvent?: {
+        topic?: string;
+        payload?: string;
+    };
+    /** True when a `block` hook failed — caller must abort/fail. */
+    blocked: boolean;
+    /** Detail message for the first blocking failure, if any. */
+    blockedMessage?: string;
+    /** True when a `suspend` hook fired and the run should stop (out-of-process
+     * phases can't block; the caller is responsible for tearing down). */
+    suspended: boolean;
+}
+export interface RunPhaseHooksOptions {
+    iteration?: number;
+    gitShaBefore?: string;
+    gitShaAfter?: string;
+    stopReason?: string;
+}
+/**
+ * Run every hook configured for `phase`, in declaration order, applying each
+ * hook's error policy and (if configured) parsing a mutation directive from
+ * its stdout. Later hooks in the same phase see the not-yet-applied original
+ * inputs — mutation from multiple hooks in one phase is last-write-wins
+ * (whichever hook mutates last), which keeps the model simple and matches
+ * the common case of a single hook per phase.
+ */
+export declare function runPhaseHooks(loop: LoopContext, phase: HookPhase, hookEnv: HookEnv, opts?: RunPhaseHooksOptions): Promise<PhaseHookResult>;

package/dist/hooks.js

@@ -0,0 +1,239 @@
+import { spawnSync } from "node:child_process";
+import { appendEvent } from "@mobrienv/autoloop-core/journal";
+import { log, printHookOutput } from "./display.js";
+import { writeSuspendState } from "./suspend-state.js";
+export function buildHookEnv(loop, extra) {
+    const env = {
+        // The work dir is the repo being worked (where .autoloop/issue-sync.toml lives);
+        // projectDir can be the preset directory, which is not what hooks want.
+        AUTOLOOP_PROJECT_DIR: loop.paths.workDir,
+        AUTOLOOP_RUN_ID: loop.runtime.runId,
+        AUTOLOOP_PRESET: loop.launch.preset,
+        AUTOLOOP_TASKS_FILE: loop.paths.tasksFile,
+    };
+    if (extra?.iteration !== undefined) {
+        env.AUTOLOOP_ITERATION = String(extra.iteration);
+    }
+    if (extra?.gitShaBefore !== undefined) {
+        env.AUTOLOOP_GIT_SHA_BEFORE = extra.gitShaBefore;
+    }
+    if (extra?.gitShaAfter !== undefined) {
+        env.AUTOLOOP_GIT_SHA_AFTER = extra.gitShaAfter;
+    }
+    if (extra?.stopReason !== undefined) {
+        env.AUTOLOOP_STOP_REASON = extra.stopReason;
+    }
+    return env;
+}
+export function captureGitSha(cwd) {
+    try {
+        const result = spawnSync("git", ["rev-parse", "HEAD"], {
+            cwd,
+            encoding: "utf-8",
+        });
+        if (result.status === 0 && result.stdout) {
+            return result.stdout.trim();
+        }
+    }
+    catch {
+        /* not a git repo or git not available — return empty */
+    }
+    return "";
+}
+function spawnHook(loop, name, cmd, hookEnv) {
+    const env = { ...process.env };
+    for (const [k, v] of Object.entries(hookEnv)) {
+        if (v !== undefined)
+            env[k] = v;
+    }
+    const result = spawnSync(cmd, {
+        shell: true,
+        cwd: loop.paths.workDir,
+        encoding: "utf-8",
+        env,
+    });
+    const combined = (result.stdout ?? "") +
+        (result.stderr ? `\n[stderr]\n${result.stderr}` : "");
+    const failed = result.status !== 0 || Boolean(result.error);
+    if (failed && result.error) {
+        log(loop, "debug", `hook ${name} spawn error: ${result.error.message}`);
+    }
+    return { status: result.status ?? -1, combined, failed };
+}
+/**
+ * Legacy single-hook entry point (`runHook`). Kept for backward compatibility
+ * with any external callers/tests; internally the engine runs hooks through
+ * `runPhaseHooks` which layers policy + mutation on top of this same spawn +
+ * journal behavior.
+ */
+export function runHook(loop, name, cmd, hookEnv, iteration) {
+    if (!cmd)
+        return;
+    log(loop, "debug", `hook ${name} start cmd=${JSON.stringify(cmd)}`);
+    const { status, combined, failed } = spawnHook(loop, name, cmd, hookEnv);
+    appendEvent(loop.paths.journalFile, loop.runtime.runId, iteration ?? "", "hook.output", `"hook": ${JSON.stringify(name)}, "exit_code": ${status}, "output": ${JSON.stringify(combined.trim())}`);
+    printHookOutput(name, status, combined.trim(), failed);
+    if (failed) {
+        const msg = firstFailureLine(name, status, combined);
+        log(loop, "warn", msg);
+        if (loop.hooks.strict && name === "pre_run") {
+            throw new Error(`Aborting run: ${msg}`);
+        }
+    }
+    else {
+        log(loop, "debug", `hook ${name} ok`);
+    }
+}
+function firstFailureLine(name, status, combined) {
+    const stderrIdx = combined.indexOf("\n[stderr]\n");
+    const detail = (stderrIdx >= 0 ? combined.slice(stderrIdx + 10) : "").trim() ||
+        (stderrIdx >= 0 ? combined.slice(0, stderrIdx) : combined).trim();
+    const firstLine = detail
+        .split("\n")
+        .map((l) => l.trim())
+        .find((l) => l.length > 0) ?? "";
+    return `hook ${name} failed (exit ${status}): ${firstLine}`;
+}
+// --- Mutation directive parsing --------------------------------------------
+const MUTATE_FENCE_RE = /<<<AUTOLOOP_MUTATE>>>\n?([\s\S]*?)\n?<<<END>>>/;
+/**
+ * Parse a mutation directive from hook stdout, given which kind of mutation
+ * this hook is configured for:
+ *
+ * - `mutate="prompt"`: a fenced block (`<<<AUTOLOOP_MUTATE>>> ... <<<END>>>`)
+ *   or a `{"prompt": "..."}` JSON line take precedence; otherwise the *entire*
+ *   trimmed stdout becomes the new prompt (so a hook can be as simple as
+ *   `echo "new prompt text"`).
+ * - `mutate="event"`: requires a JSON object with `topic` and/or `payload`
+ *   (there is no plain-text form — an emitted event is structured, not free
+ *   text).
+ *
+ * Empty/malformed stdout is not an error — it simply yields no mutation
+ * (returns null), since a hook may run for its side effects alone.
+ */
+export function parseMutationDirective(stdout, mutate) {
+    if (!stdout?.trim())
+        return null;
+    const trimmed = stdout.trim();
+    const fenced = MUTATE_FENCE_RE.exec(stdout);
+    if (fenced && mutate === "prompt") {
+        return { prompt: fenced[1] };
+    }
+    if (trimmed.startsWith("{")) {
+        try {
+            const obj = JSON.parse(trimmed);
+            const out = {};
+            if (typeof obj.prompt === "string")
+                out.prompt = obj.prompt;
+            if (typeof obj.topic === "string")
+                out.topic = obj.topic;
+            if (typeof obj.payload === "string")
+                out.payload = obj.payload;
+            if (Object.keys(out).length > 0)
+                return out;
+        }
+        catch {
+            /* not JSON — fall through to the plain-text prompt case below */
+        }
+    }
+    if (mutate === "prompt")
+        return { prompt: trimmed };
+    return null;
+}
+/**
+ * Run every hook configured for `phase`, in declaration order, applying each
+ * hook's error policy and (if configured) parsing a mutation directive from
+ * its stdout. Later hooks in the same phase see the not-yet-applied original
+ * inputs — mutation from multiple hooks in one phase is last-write-wins
+ * (whichever hook mutates last), which keeps the model simple and matches
+ * the common case of a single hook per phase.
+ */
+export async function runPhaseHooks(loop, phase, hookEnv, opts = {}) {
+    // Defensive default: hand-built test LoopContexts (and any older caller
+    // that predates `hooks.specs`) may omit it entirely.
+    const specs = (loop.hooks.specs ?? []).filter((s) => s.phase === phase);
+    const result = { blocked: false, suspended: false };
+    const iterationStr = opts.iteration !== undefined ? String(opts.iteration) : "";
+    for (const spec of specs) {
+        if (!spec.command)
+            continue;
+        log(loop, "debug", `hook ${phase} start cmd=${JSON.stringify(spec.command)} on_error=${spec.onError} mutate=${spec.mutate}`);
+        const { status, combined, failed } = spawnHook(loop, phase, spec.command, hookEnv);
+        appendEvent(loop.paths.journalFile, loop.runtime.runId, iterationStr, "hook.output", `"hook": ${JSON.stringify(phase)}, "exit_code": ${status}, "output": ${JSON.stringify(combined.trim())}`);
+        printHookOutput(phase, status, combined.trim(), failed);
+        if (!failed && spec.mutate !== "none") {
+            const stdoutOnly = combined.split("\n[stderr]\n")[0];
+            const directive = parseMutationDirective(stdoutOnly, spec.mutate);
+            if (directive) {
+                if (spec.mutate === "prompt" && directive.prompt !== undefined) {
+                    result.mutatedPrompt = directive.prompt;
+                }
+                else if (spec.mutate === "event") {
+                    result.mutatedEvent = {
+                        topic: directive.topic,
+                        payload: directive.payload,
+                    };
+                }
+            }
+        }
+        if (!failed) {
+            log(loop, "debug", `hook ${phase} ok`);
+            continue;
+        }
+        const msg = firstFailureLine(phase, status, combined);
+        switch (spec.onError) {
+            case "warn":
+                log(loop, "warn", msg);
+                break;
+            case "block":
+                log(loop, "error", `hook ${phase} blocked run: ${msg}`);
+                result.blocked = true;
+                result.blockedMessage = msg;
+                return result;
+            case "suspend": {
+                // Durable suspend: write versioned state and stop this call site
+                // immediately. The run process ends (see stopSuspended in the
+                // call sites); a later `autoloop resume` (a fresh process) reads
+                // suspend-state.json and continues from `resumeIteration`. This
+                // deliberately does NOT block in-process — emit's pre_emit/post_emit
+                // hooks run in a disposable subprocess and could never block the
+                // harness loop anyway, so in-process phases use the same simple,
+                // uniform "stop and let resume pick it back up" contract.
+                log(loop, "warn", `hook ${phase} suspended run: ${msg}`);
+                const resumeIteration = suspendResumeIteration(phase, opts.iteration);
+                writeSuspendState(loop.paths.stateDir, {
+                    runId: loop.runtime.runId,
+                    phase,
+                    iteration: opts.iteration ?? 0,
+                    reason: msg,
+                    hookCommand: spec.command,
+                    createdAt: new Date().toISOString(),
+                    resumeIteration,
+                }, loop.paths.journalFile);
+                result.suspended = true;
+                result.blockedMessage = msg;
+                return result;
+            }
+        }
+    }
+    return result;
+}
+function suspendResumeIteration(phase, iteration) {
+    const iter = iteration ?? 0;
+    switch (phase) {
+        case "pre_run":
+            return 1;
+        case "pre_iteration":
+            return iter;
+        case "post_iteration":
+        case "post_emit":
+            return iter + 1;
+        case "pre_emit":
+            return iter;
+        case "post_run":
+            return iter + 1;
+        default:
+            return iter;
+    }
+}
+//# sourceMappingURL=hooks.js.map

package/dist/hooks.js.map

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

package/dist/index.d.ts

@@ -1,6 +1,19 @@
+import type { LiveControlAdapter } from "./control/adapter.js";
 import { emit as emitCmd } from "./emit.js";
-import type { LoopContext, RunOptions, RunSummary } from "./types.js";
-export type { LoopContext, RunOptions, RunSummary };
+import type { LoopContext, RunOptions, RunSummary, StopReason } from "./types.js";
+export { STOP_REASONS } from "./types.js";
+export type { LoopContext, RunOptions, RunSummary, StopReason };
 export declare function run(projectDir: string, promptOverride: string | null, selfCommand: string, runOptions: RunOptions): Promise<RunSummary>;
+/**
+ * Drive the iteration loop for an already-built, already-registered
+ * LoopContext, starting at `startIteration`. Owns abort/teardown wiring,
+ * the tracked-iterate recursion, session cleanup, post-run worktree
+ * lifecycle, and finish notifications. Shared by `run()` and `resume()` so
+ * both paths exercise identical signal handlers, stop handlers, and
+ * registry/journal behavior.
+ */
+export declare function driveLoop(loop: LoopContext, runOptions: RunOptions, startIteration: number): Promise<RunSummary>;
+export { buildResumeContext, determineResumeIteration, type ResumeOptions, type ResumeResult, resume, } from "./resume.js";
 export { emitCmd as emit };
 export declare function runParallelBranchCli(projectDir: string, branchDir: string, selfCommand: string, onEvent?: (event: import("./events.js").LoopEvent) => void): Promise<void>;
+export declare function buildControlAdapter(loop: LoopContext): LiveControlAdapter | undefined;