@mobrienv/autoloop-harness 0.8.0 → 0.9.2

package/dist/iteration-diff.js

@@ -0,0 +1,92 @@
+import { extractField, extractIteration, extractTopic, } from "@mobrienv/autoloop-core/journal";
+function linesOf(runLines, iter) {
+    const want = String(iter);
+    return runLines.filter((l) => extractIteration(l) === want);
+}
+function fieldFor(lines, topic, field) {
+    // Last matching line wins (the final value journaled for that iteration).
+    for (let i = lines.length - 1; i >= 0; i--) {
+        if (extractTopic(lines[i]) === topic)
+            return extractField(lines[i], field);
+    }
+    return "";
+}
+function topicsOf(lines) {
+    return new Set(lines.map((l) => extractTopic(l)).filter(Boolean));
+}
+function costOf(lines) {
+    let sum = 0;
+    for (const l of lines) {
+        if (extractTopic(l) !== "backend.usage")
+            continue;
+        const v = Number(extractField(l, "cost_usd"));
+        if (Number.isFinite(v))
+            sum += v;
+    }
+    return Math.round(sum * 1e6) / 1e6;
+}
+/** Multiset line diff: counts of lines present in b-not-a (added) / a-not-b (removed). */
+function textDelta(a, b) {
+    const aLines = a ? a.split("\n") : [];
+    const bLines = b ? b.split("\n") : [];
+    const count = (xs) => {
+        const m = new Map();
+        for (const x of xs)
+            m.set(x, (m.get(x) ?? 0) + 1);
+        return m;
+    };
+    const am = count(aLines);
+    const bm = count(bLines);
+    let added = 0;
+    let removed = 0;
+    for (const [line, n] of bm)
+        added += Math.max(0, n - (am.get(line) ?? 0));
+    for (const [line, n] of am)
+        removed += Math.max(0, n - (bm.get(line) ?? 0));
+    return {
+        aChars: a.length,
+        bChars: b.length,
+        charDelta: b.length - a.length,
+        linesAdded: added,
+        linesRemoved: removed,
+        changed: a !== b,
+    };
+}
+/**
+ * Structural diff between two journaled iterations of a run: prompt (assembled
+ * context), backend output, cost, and the emitted-event topic set. Pure over
+ * the run's journal lines — the durable journal is the trustworthy source.
+ */
+export function diffIterations(runLines, iterA, iterB) {
+    const a = linesOf(runLines, iterA);
+    const b = linesOf(runLines, iterB);
+    const aTopics = topicsOf(a);
+    const bTopics = topicsOf(b);
+    const aUsd = costOf(a);
+    const bUsd = costOf(b);
+    return {
+        iterA,
+        iterB,
+        prompt: textDelta(fieldFor(a, "iteration.start", "prompt"), fieldFor(b, "iteration.start", "prompt")),
+        output: textDelta(fieldFor(a, "iteration.finish", "output"), fieldFor(b, "iteration.finish", "output")),
+        cost: { aUsd, bUsd, deltaUsd: Math.round((bUsd - aUsd) * 1e6) / 1e6 },
+        events: {
+            onlyInA: [...aTopics].filter((t) => !bTopics.has(t)).sort(),
+            onlyInB: [...bTopics].filter((t) => !aTopics.has(t)).sort(),
+        },
+    };
+}
+/** Render a structural iteration diff as a human-readable report. */
+export function renderIterationDiff(runId, d) {
+    const t = (label, x) => `${label}: ${x.changed ? "changed" : "identical"} (${x.aChars}→${x.bChars} chars, Δ${x.charDelta >= 0 ? "+" : ""}${x.charDelta}; +${x.linesAdded}/-${x.linesRemoved} lines)`;
+    return [
+        `## Diff ${runId}: iter ${d.iterA} → ${d.iterB}`,
+        "",
+        t("prompt/context", d.prompt),
+        t("output", d.output),
+        `cost: $${d.cost.aUsd} → $${d.cost.bUsd} (Δ${d.cost.deltaUsd >= 0 ? "+" : ""}${d.cost.deltaUsd})`,
+        `events only in ${d.iterA}: ${d.events.onlyInA.join(", ") || "(none)"}`,
+        `events only in ${d.iterB}: ${d.events.onlyInB.join(", ") || "(none)"}`,
+    ].join("\n");
+}
+//# sourceMappingURL=iteration-diff.js.map

package/dist/iteration-diff.js.map

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

package/dist/iteration.d.ts

@@ -10,7 +10,27 @@ export declare function resolveOutcome(ctx: {
     completionEvent: string;
     requiredEvents: string[];
     completionPromise: string;
+    hasBlockingTasks: boolean;
+    /**
+     * Ralph-parity ordering policy. When true, a completion claim is rejected
+     * (falls through to the routed/promise/continue branches) unless
+     * `completionOrderOk` confirms no other event followed completionEvent in
+     * its own turn. Optional/false = order-insensitive set-membership check
+     * (unchanged default behavior).
+     */
+    mustBeLast?: boolean;
+    /** Precomputed by the caller from full journal ordering (see completionEmittedLast). */
+    completionOrderOk?: boolean;
 }): {
     action: string;
     outcome: string;
 };
+/**
+ * True iff `completionEvent`, wherever it was last emitted in the run, was
+ * the last non-system topic emitted in that same turn (iteration). Used to
+ * enforce `completion.must_be_last`: ralph rejects completion if other
+ * events follow it within the same turn, rather than autoloop's default
+ * order-insensitive set-membership check. Returns true (not applicable) if
+ * the completion event has not been emitted at all.
+ */
+export declare function completionEmittedLast(runLines: string[], completionEvent: string): boolean;

package/dist/iteration.js

@@ -1,19 +1,47 @@
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
-import { runAcpIteration, runClaudeSdkIteration, runPiIteration, } from "@mobrienv/autoloop-backends";
+import { classifyBackendError, runAcpIteration, runClaudeSdkIteration, runPiIteration, } from "@mobrienv/autoloop-backends";
 import { initAcpSession, terminateAcpSession, } from "@mobrienv/autoloop-backends/acp-client";
+import { providerLaunchArgs } from "@mobrienv/autoloop-backends/acp-providers";
 import { getClaudeSdkUsage, initClaudeSdkSession, terminateClaudeSdkSession, } from "@mobrienv/autoloop-backends/claude-sdk-client";
 import { getPiSessionStats, initPiSession, resetPiSession, terminatePiSession, } from "@mobrienv/autoloop-backends/pi-rpc-client";
-import { jsonFieldRaw, listText } from "@mobrienv/autoloop-core";
-import { appendEvent, extractField, extractIteration, extractTopic, readRunLines, } from "@mobrienv/autoloop-core/journal";
+import { jsonField, jsonFieldRaw, listText } from "@mobrienv/autoloop-core";
+import { appendEvent, appendOperatorEvent, extractField, extractIteration, extractTopic, readRunLines, } from "@mobrienv/autoloop-core/journal";
+import { materializeOpenFrom } from "@mobrienv/autoloop-core/tasks";
+import * as topology from "@mobrienv/autoloop-core/topology";
+import { reinjectAcceptanceFailure, runAcceptanceGate } from "./acceptance.js";
+import { awaitHumanResponse } from "./ask.js";
+import { backoffDelayMs, circuitDecision, countTransientPauses, } from "./circuit-breaker.js";
 import { log } from "./display.js";
 import { appendInvalidEvent, invalidEvent, parallelTriggerTopic, systemTopic, } from "./emit.js";
+import { runFileModAudit } from "./file-mod-audit.js";
 import { loopStartMs } from "./guards.js";
-import { appendBackendFinish, appendBackendStart, appendIterationFinish, appendIterationStart, buildBackendCommand, runProcess, } from "./parallel.js";
+import { buildHookEnv, captureGitSha, runPhaseHooks } from "./hooks.js";
+import { reinjectIntentFailure, runIntentCriteria } from "./intent.js";
+import { appendBackendFinish, appendBackendStart, appendIterationFinish, appendIterationStart, buildBackendCommand, commandUsageFilePath, runProcessAsync, } from "./parallel.js";
+import { reinjectPostconditionFailure, runPostconditionGuards, } from "./postconditions.js";
+import { runProgressMetric } from "./progress.js";
 import { buildIterationContext } from "./prompt.js";
+import { consumeHumanAck, enterProvisional, holdProvisional, releaseProvisional, resolveProvisional, } from "./provisional.js";
 import { registryProgress } from "./registry-bridge.js";
-import { completeLoop, stopBackendFailed, stopBackendTimeout, stopMaxRuntime, } from "./stop.js";
-import { continueAfterParallelJoin, executeParallelWave, stopAfterParallelWave, } from "./wave.js";
+import { finishStageIteration } from "./stage.js";
+import { completeLoop, stopBackendErrorClass, stopBackendFailed, stopBackendTimeout, stopMaxRuntime, stopSuspended, } from "./stop.js";
+import { readSuspendState, resumeRequested } from "./suspend-state.js";
+import { reinjectTamperFailure, runTamperScreen } from "./tamper.js";
+import { continueAfterParallelJoin, executeDeclarativeWave, executeParallelWave, stopAfterParallelWave, } from "./wave.js";
 export async function runIteration(loop, iteration, iterate) {
+    // Out-of-process pre_emit/post_emit `suspend` hooks (run in the `emit`
+    // subprocess — see emit.ts:runEmitPhaseHooks) can't block the harness loop
+    // directly; they write durable suspend state instead. Detect it here, at
+    // the next iteration boundary, and halt the loop rather than silently
+    // continuing past a pending suspend.
+    const pendingEmitSuspend = readSuspendState(loop.paths.stateDir);
+    if (pendingEmitSuspend &&
+        (pendingEmitSuspend.phase === "pre_emit" ||
+            pendingEmitSuspend.phase === "post_emit") &&
+        !resumeRequested(loop.paths.stateDir)) {
+        return stopSuspended(loop, iteration, pendingEmitSuspend.reason);
+    }
     let iter = buildIterationContext(loop, iteration);
     // Clamp the iteration timeout to the remaining loop wall-clock budget so a
     // long iteration never overshoots event_loop.max_runtime. Applied before
@@ -48,6 +76,20 @@ export async function runIteration(loop, iteration, iterate) {
     appendBackendStart(loop, iter);
     log(loop, "debug", `backend start command=${iter.backend.command}`);
     const startEpoch = Math.floor(Date.now() / 1000);
+    const gitShaBefore = captureGitSha(loop.paths.workDir);
+    const preIterResult = await runPhaseHooks(loop, "pre_iteration", buildHookEnv(loop, { iteration, gitShaBefore }), { iteration, gitShaBefore });
+    if (preIterResult.blocked) {
+        throw new Error(`Aborting run: ${preIterResult.blockedMessage ?? "pre_iteration hook blocked"}`);
+    }
+    if (preIterResult.suspended) {
+        return stopSuspended(loop, iteration, preIterResult.blockedMessage ?? "pre_iteration hook suspended the run");
+    }
+    // Mutation seam: applied after buildIterationContext but before the backend
+    // command is built, so a mutated prompt survives the loop-budget timeout
+    // clamp's `iter = {...iter, backend:{...}}` reassignment above.
+    if (preIterResult.mutatedPrompt !== undefined) {
+        iter = { ...iter, prompt: preIterResult.mutatedPrompt };
+    }
     // Fresh ACP session per iteration — ensures each role (researcher, critic,
     // etc.) starts with a clean context window for truly independent review.
     if (iter.backend.kind === "acp") {
@@ -63,7 +105,7 @@ export async function runIteration(loop, iteration, iterate) {
         const acpOpts = {
             provider: iter.backend.provider,
             command: iter.backend.command,
-            args: iter.backend.args,
+            args: providerLaunchArgs(iter.backend.provider, iter.backend.profile, iter.backend.args),
             cwd: loop.paths.workDir,
             trustAllTools: iter.backend.trustAllTools,
             agentName: iter.backend.agent || undefined,
@@ -98,6 +140,7 @@ export async function runIteration(loop, iteration, iterate) {
             model: iter.backend.model || undefined,
             cwd: loop.paths.workDir,
             trustAllTools: iter.backend.trustAllTools,
+            disallowedTools: iter.backend.disallowedTools,
             verbose: loop.runtime.logLevel === "debug",
         });
         log(loop, "debug", `new claude-sdk session for iteration ${iteration} model="${iter.backend.model || "default"}"`);
@@ -106,7 +149,21 @@ export async function runIteration(loop, iteration, iterate) {
     const elapsedS = Math.floor(Date.now() / 1000) - startEpoch;
     appendBackendFinish(loop, iter, output, exitCode, timedOut);
     appendIterationFinish(loop, iter, output, exitCode, timedOut, elapsedS);
+    const gitShaAfter = captureGitSha(loop.paths.workDir);
+    const postIterResult = await runPhaseHooks(loop, "post_iteration", buildHookEnv(loop, { iteration, gitShaBefore, gitShaAfter }), { iteration, gitShaBefore, gitShaAfter });
+    if (postIterResult.blocked) {
+        throw new Error(`Aborting run: ${postIterResult.blockedMessage ?? "post_iteration hook blocked"}`);
+    }
+    if (postIterResult.suspended) {
+        return stopSuspended(loop, iteration, postIterResult.blockedMessage ?? "post_iteration hook suspended the run");
+    }
     registryProgress(loop, iteration);
+    // Capture the preset-declared progress scalar each iteration (drift signal).
+    runProgressMetric(loop, iteration);
+    // Emit-boundary file-mod audit (opt-in): flag file writes by a role with
+    // disallowed_tools/read_only. Purely observational — journals/emits a typed
+    // event for parent orchestrators; never alters control flow itself.
+    runFileModAudit(loop, iter, iteration);
     log(loop, "debug", `iteration ${iteration} finish exit_code=${exitCode}`);
     loop.onEvent?.({
         type: "iteration.footer",
@@ -121,10 +178,44 @@ export async function runIteration(loop, iteration, iterate) {
     }
     if (timedOut)
         return stopBackendTimeout(loop, iteration, output);
-    if (exitCode !== 0)
-        return stopBackendFailed(loop, iteration, output);
+    if (exitCode !== 0) {
+        return handleBackendFailure(loop, iteration, output, iterate);
+    }
     return finishIteration(loop, iter, output, iterate);
 }
+/**
+ * Classify a non-zero backend exit. A typed transient/rate-limit/auth/quota
+ * error is handled by the circuit breaker — retryable classes pause-and-retry
+ * (rather than fast-failing into a laundered verdict or generic death) until
+ * the breaker opens; non-retryable classes stop with a typed reason. Anything
+ * unclassified is a plain backend failure.
+ */
+async function handleBackendFailure(loop, iteration, output, iterate) {
+    const errorClass = classifyBackendError(output);
+    if (errorClass === "none")
+        return stopBackendFailed(loop, iteration, output);
+    const runLines = readRunLines(loop.paths.journalFile, loop.runtime.runId);
+    const pauses = countTransientPauses(runLines);
+    const decision = circuitDecision(errorClass, pauses, loop.limits.transientMaxPauses ?? 3);
+    if (decision.action === "stop") {
+        return stopBackendErrorClass(loop, iteration, decision.reason, output);
+    }
+    // Pause-and-retry with exponential backoff: a transient blip becomes a retry
+    // instead of run-death. The Nth retry waits base*2^(N-1), capped.
+    const attempt = pauses + 1;
+    const pauseMs = backoffDelayMs(attempt, loop.limits.transientPauseMs ?? 5000, loop.limits.transientBackoffCapMs ?? 30000);
+    appendEvent(loop.paths.journalFile, loop.runtime.runId, String(iteration), "backend.transient", jsonField("error_class", errorClass) +
+        ", " +
+        jsonField("pause_count", String(attempt)) +
+        ", " +
+        jsonFieldRaw("backoff_ms", String(pauseMs)) +
+        ", " +
+        jsonField("output_tail", output.slice(-500)));
+    log(loop, "warn", `transient backend error (${errorClass}); retry ${attempt}/${loop.limits.transientMaxPauses ?? 3} after ${pauseMs}ms backoff`);
+    if (pauseMs > 0)
+        await new Promise((r) => setTimeout(r, pauseMs));
+    return iterate(loop, iteration + 1);
+}
 async function runBackendIteration(loop, iter) {
     if (iter.backend.kind === "acp" && loop.acpSession.current) {
         return runAcpIteration(loop.acpSession.current, iter.prompt, iter.backend.timeoutMs);
@@ -139,7 +230,85 @@ async function runBackendIteration(loop, iter) {
         recordClaudeSdkUsage(loop, iter);
         return result;
     }
-    return runProcess(buildBackendCommand(loop, iter), iter.backend.timeoutMs, iter.backend.kind);
+    // Plain `command` backend (and any other non-session kind falling through
+    // here): async-spawned so the harness can register a live PID for
+    // interrupt signaling (commandControlAdapter) without blocking the event
+    // loop the way execSync does. Session is cleared as soon as the process
+    // exits, before usage telemetry is recorded.
+    const usesUsageFile = iter.backend.kind === "command" && Boolean(iter.backend.usageFrom);
+    if (usesUsageFile) {
+        // Clear any stale usage file left by a prior iteration before invoking,
+        // so a command that forgets to (re)write it is treated as zero cost
+        // rather than reporting stale numbers.
+        removeUsageFileIfExists(commandUsageFilePath(loop, iter.iteration));
+    }
+    const result = await runProcessAsync(buildBackendCommand(loop, iter), iter.backend.timeoutMs, iter.backend.kind, (pid) => {
+        loop.commandSession.current = { pid };
+    });
+    loop.commandSession.current = undefined;
+    if (iter.backend.kind === "command") {
+        recordCommandUsage(loop, iter);
+    }
+    return result;
+}
+function removeUsageFileIfExists(path) {
+    try {
+        if (existsSync(path))
+            unlinkSync(path);
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/**
+ * Journal per-iteration token/cost totals for the `command` backend, read
+ * from the opt-in `usage_from = "file"` side-file convention: the wrapped
+ * command may write a JSON object to `$AUTOLOOP_USAGE_FILE` before exiting.
+ * Best-effort and graceful: missing, empty, or unparsable files (or
+ * `usage_from` left unset) mean zero cost and no event — never an error.
+ */
+function recordCommandUsage(loop, iter) {
+    if (iter.backend.usageFrom !== "file")
+        return;
+    const path = commandUsageFilePath(loop, iter.iteration);
+    if (!existsSync(path))
+        return;
+    let parsed;
+    try {
+        const raw = readFileSync(path, "utf-8").trim();
+        if (!raw)
+            return;
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return;
+    }
+    finally {
+        removeUsageFileIfExists(path);
+    }
+    const num = (key) => {
+        const v = parsed[key];
+        return typeof v === "number" && Number.isFinite(v) ? v : 0;
+    };
+    const inputTokens = num("input_tokens");
+    const outputTokens = num("output_tokens");
+    const cacheReadTokens = num("cache_read_tokens");
+    const cacheWriteTokens = num("cache_write_tokens");
+    const totalTokens = parsed.total_tokens !== undefined
+        ? num("total_tokens")
+        : inputTokens + outputTokens + cacheReadTokens + cacheWriteTokens;
+    const costUsd = num("cost_usd");
+    appendEvent(loop.paths.journalFile, loop.runtime.runId, String(iter.iteration), "backend.usage", jsonFieldRaw("input_tokens", String(inputTokens)) +
+        ", " +
+        jsonFieldRaw("output_tokens", String(outputTokens)) +
+        ", " +
+        jsonFieldRaw("cache_read_tokens", String(cacheReadTokens)) +
+        ", " +
+        jsonFieldRaw("cache_write_tokens", String(cacheWriteTokens)) +
+        ", " +
+        jsonFieldRaw("total_tokens", String(totalTokens)) +
+        ", " +
+        jsonFieldRaw("cost_usd", String(costUsd)));
 }
 /**
  * Journal per-iteration token/cost totals from pi's get_session_stats.
@@ -238,12 +407,52 @@ export async function finishIteration(loop, iter, output, iterate) {
         emittedTopic,
         outcome,
     });
+    // Human-in-the-loop: a `human.ask` event pauses the loop until an operator
+    // responds (or the timeout elapses); the answer is injected into the next
+    // iteration as guidance. Handled before routing so the ask topic itself is
+    // never treated as a routing/invalid event.
+    if (loop.ask?.enabled && emitted.topic === loop.ask.event) {
+        return finishAskIteration(loop, iter, emitted.payload, iterate, progress);
+    }
     if (invalidEvent(emitted.topic, iter.allowedEvents, loop.parallel.enabled, loop.completion.event)) {
         return rejectInvalidAndContinue(loop, iter, emitted.topic, iterate, progress);
     }
     if (parallelTriggerTopic(emitted.topic)) {
         return finishParallelIteration(loop, iter, emitted.topic, emitted.payload, iterate, progress);
     }
+    // Fan-out `[[stage]]` dispatch: a stage's `trigger` is a plain declared
+    // event (already passed the invalid-event check above like any other
+    // event), but the harness intercepts it here instead of ordinary role
+    // dispatch — launch the stage's branches, reduce, and route at the
+    // reducer's onPass/onFail event, exactly as a `.parallel` wave intercepts
+    // its dispatch topic above.
+    const stage = topology.stageForTrigger(loop.topology, emitted.topic);
+    if (stage) {
+        progress(emitted.topic, "stage:dispatched");
+        return finishStageIteration(loop, iter, stage, emitted.topic, iterate);
+    }
+    // Declarative concurrency (ralph v3 style): if the just-emitted event
+    // routes (via [handoff]) to a role that declares `concurrency > 0`, the
+    // harness auto-launches N concurrent branches for that role — no agent
+    // `.parallel` emit required. This takes precedence over ordinary routing
+    // for that event; agent-triggered `.parallel` (handled above) is
+    // unaffected and remains fully backward compatible. Synthetic wave/joined
+    // topics (`wave.*`, `*.parallel.joined`) never re-enter this path since
+    // `emitted.topic` is always an agent-emitted, non-system event here.
+    if (loop.parallel.enabled) {
+        const concurrentRoles = topology.concurrentRolesForEvent(loop.topology, emitted.topic);
+        if (concurrentRoles.length > 0) {
+            // Execution is synchronous (one wave resolves per iteration); when an
+            // event routes to more than one concurrency role, the first declared
+            // role's wave runs this iteration — the routing event still applies
+            // (via the resume topic) on subsequent iterations for any others.
+            return finishDeclarativeIteration(loop, iter, emitted.topic, concurrentRoles[0], iterate, progress);
+        }
+    }
+    // Open-task gate for the completion-promise path. Mirror the event-path gate
+    // in emit.ts (same store via loop.paths.tasksFile, soft tasks are advisory)
+    // so a stdout promise can't bypass the requirement the emitted event honors.
+    const hasBlockingTasks = materializeOpenFrom(loop.paths.tasksFile).some((t) => t.soft !== true);
     const resolved = resolveOutcome({
         emittedTopic: emitted.topic,
         allTopics,
@@ -252,12 +461,119 @@ export async function finishIteration(loop, iter, output, iterate) {
         completionEvent: loop.completion.event,
         requiredEvents: loop.completion.requiredEvents,
         completionPromise: loop.completion.promise,
+        hasBlockingTasks,
+        mustBeLast: loop.completion.mustBeLast,
+        completionOrderOk: completionEmittedLast(runLines, loop.completion.event),
     });
     progress(emitted.topic, resolved.outcome);
-    if (resolved.action === "complete_event")
-        return completeLoop(loop, iter.iteration, "completion_event");
-    if (resolved.action === "complete_promise")
-        return completeLoop(loop, iter.iteration, "completion_promise");
+    if (resolved.action === "complete_event" ||
+        resolved.action === "complete_promise") {
+        const reason = resolved.action === "complete_event"
+            ? "completion_event"
+            : "completion_promise";
+        // Provisional-done hold: a self-asserted done-claim parks in
+        // `awaiting_acceptance` before any irreversible action and is released only
+        // when the deterministic gates pass (or an operator acknowledges).
+        enterProvisional(loop, iter.iteration, reason);
+        // Out-of-band acceptance gate: the harness runs deterministic verify
+        // commands on the done-claim.
+        const gate = runAcceptanceGate(loop, iter.iteration);
+        // Required-absence guards: catch reward-hacks (leftover TODO, skipped
+        // tests, secrets, dirty tree) the verify commands and LLM gates may miss.
+        // Only run when the acceptance gate passed (the run is already held
+        // otherwise).
+        const guards = gate.passed
+            ? runPostconditionGuards(loop, iter.iteration)
+            : { ran: false, passed: false, violations: [] };
+        // Anti-reward-hack screen: under bypassPermissions the maker can edit the
+        // very tests that gate it, so a test-backed "done" is screened for test
+        // tampering before release.
+        const tamper = gate.passed
+            ? runTamperScreen(loop, iter.iteration)
+            : { ran: false, passed: false, violations: [] };
+        // Intent-binding: the build must satisfy the stated acceptance criteria,
+        // not just pass its tests.
+        const intent = gate.passed
+            ? runIntentCriteria(loop, iter.iteration)
+            : { ran: false, passed: false, failures: [] };
+        const humanAck = consumeHumanAck(loop);
+        const state = resolveProvisional({
+            acceptancePassed: gate.passed,
+            postconditionsPassed: guards.passed && tamper.passed && intent.passed,
+            humanAck,
+        });
+        if (state === "accepted") {
+            releaseProvisional(loop, iter.iteration, humanAck);
+            return completeLoop(loop, iter.iteration, reason);
+        }
+        // Held: re-inject the most specific failure and route back to rework.
+        let cause = "acceptance";
+        if (!gate.passed) {
+            reinjectAcceptanceFailure(loop, iter.iteration, gate);
+        }
+        else if (!guards.passed) {
+            reinjectPostconditionFailure(loop, iter.iteration, guards);
+            cause = "postcondition";
+        }
+        else if (!tamper.passed) {
+            reinjectTamperFailure(loop, iter.iteration, tamper);
+            cause = "tamper";
+        }
+        else {
+            reinjectIntentFailure(loop, iter.iteration, intent);
+            cause = "intent";
+        }
+        holdProvisional(loop, iter.iteration, cause);
+        progress(emitted.topic, "hold:awaiting_acceptance");
+        return iterate(loop, iter.iteration + 1);
+    }
+    return iterate(loop, iter.iteration + 1);
+}
+/**
+ * Block the loop on a `human.ask` until an operator responds (via the `respond`
+ * control verb) or the timeout elapses, then continue. The answer is injected
+ * into the next iteration's prompt via the existing operator-guidance path.
+ */
+async function finishAskIteration(loop, iter, question, iterate, progress) {
+    const runId = loop.runtime.runId;
+    const iteration = String(iter.iteration);
+    const questionId = `ask_${runId}_${iter.iteration}`;
+    appendEvent(loop.paths.journalFile, runId, iteration, "ask.pending", `${jsonField("question_id", questionId)}, ${jsonField("question", question)}`);
+    loop.onEvent?.({
+        type: "ask.pending",
+        runId,
+        iteration: iter.iteration,
+        questionId,
+        question,
+    });
+    progress(loop.ask.event, "ask:waiting");
+    const answer = await awaitHumanResponse({
+        stateDir: loop.paths.stateDir,
+        runId,
+        questionId,
+        timeoutMs: loop.ask.timeoutMs,
+        pollMs: loop.ask.pollMs,
+        signal: loop.signal,
+    });
+    if (answer === null) {
+        if (loop.signal?.aborted) {
+            return { iterations: iter.iteration, stopReason: "interrupted", runId };
+        }
+        appendEvent(loop.paths.journalFile, runId, iteration, "ask.timeout", jsonField("question_id", questionId));
+        progress(loop.ask.event, "ask:timeout");
+        return iterate(loop, iter.iteration + 1);
+    }
+    appendEvent(loop.paths.journalFile, runId, iteration, "ask.answered", `${jsonField("question_id", questionId)}, ${jsonField("answer", answer)}`);
+    // Inject the answer into the next prompt via the operator-guidance path.
+    appendOperatorEvent(loop.paths.journalFile, runId, iteration, "operator.guidance", `Human response to "${question}": ${answer}`);
+    loop.onEvent?.({
+        type: "ask.answered",
+        runId,
+        iteration: iter.iteration,
+        questionId,
+        answer,
+    });
+    progress(loop.ask.event, "ask:answered");
     return iterate(loop, iter.iteration + 1);
 }
 async function rejectInvalidAndContinue(loop, iter, emittedTopic, iterate, progress) {
@@ -275,14 +591,38 @@ async function finishParallelIteration(loop, iter, emittedTopic, emittedPayload,
     progress(emittedTopic, `parallel:stop:${result.reason}`);
     return stopAfterParallelWave(loop, iter, result.reason, result.waveId);
 }
+/**
+ * Declarative-wave counterpart of `finishParallelIteration`: the routing
+ * event itself (not an agent `.parallel` emit) triggers N concurrent
+ * branches for `role`, per its topology `concurrency` declaration. Join/stop
+ * handling mirrors the agent-triggered path so downstream resume routing
+ * (`continueAfterParallelJoin`/`stopAfterParallelWave`) behaves identically.
+ */
+async function finishDeclarativeIteration(loop, iter, routingEvent, role, iterate, progress) {
+    const result = executeDeclarativeWave(loop, iter, role, routingEvent);
+    const syntheticTopic = `${routingEvent}.parallel`;
+    if (result.reason === "parallel_wave_complete") {
+        progress(syntheticTopic, "parallel:joined");
+        return continueAfterParallelJoin(loop, iter, result.waveId, syntheticTopic, result.elapsedMs, iterate);
+    }
+    progress(syntheticTopic, `parallel:stop:${result.reason}`);
+    return stopAfterParallelWave(loop, iter, result.reason, result.waveId);
+}
 export function resolveOutcome(ctx) {
-    if (completedViaEvent(ctx.allTopics, ctx.completionEvent, ctx.requiredEvents)) {
+    if (completedViaEvent(ctx.allTopics, ctx.completionEvent, ctx.requiredEvents) &&
+        (!ctx.mustBeLast || ctx.completionOrderOk)) {
         return { action: "complete_event", outcome: "complete:completion_event" };
     }
     if (shouldContinueFromAcceptedEvent(ctx.emittedTopic, ctx.completionEvent)) {
         return { action: "continue_routed", outcome: "continue:routed_event" };
     }
+    // The stdout promise is a fallback, not a self-grade: a substring match alone
+    // must never finish a run. It is accepted only when the run also clears the
+    // same gates the completion event must clear — no invalid events this turn,
+    // every required event seen, and no open blocking tasks.
     if (!ctx.hadInvalidEvents &&
+        !ctx.hasBlockingTasks &&
+        requiredEventsSatisfied(ctx.allTopics, ctx.requiredEvents) &&
         completedViaPromise(ctx.output, ctx.completionPromise)) {
         return {
             action: "complete_promise",
@@ -300,10 +640,37 @@ function latestAgentEventRecord(lines) {
     }
     return { topic: "", payload: "" };
 }
+/**
+ * True iff `completionEvent`, wherever it was last emitted in the run, was
+ * the last non-system topic emitted in that same turn (iteration). Used to
+ * enforce `completion.must_be_last`: ralph rejects completion if other
+ * events follow it within the same turn, rather than autoloop's default
+ * order-insensitive set-membership check. Returns true (not applicable) if
+ * the completion event has not been emitted at all.
+ */
+export function completionEmittedLast(runLines, completionEvent) {
+    let completionIteration = null;
+    for (const line of runLines) {
+        if (extractTopic(line) === completionEvent) {
+            completionIteration = extractIteration(line);
+        }
+    }
+    if (completionIteration === null)
+        return true;
+    const turnTopics = runLines
+        .filter((line) => extractIteration(line) === completionIteration)
+        .map(extractTopic)
+        .filter((topic) => topic !== "" && !systemTopic(topic));
+    return turnTopics.lastIndexOf(completionEvent) === turnTopics.length - 1;
+}
+/** Every required-evidence event has been seen in the run so far. */
+function requiredEventsSatisfied(topics, requiredEvents) {
+    return requiredEvents.every((e) => topics.includes(e));
+}
 function completedViaEvent(topics, completionEvent, requiredEvents) {
     if (!topics.includes(completionEvent))
         return false;
-    return requiredEvents.every((e) => topics.includes(e));
+    return requiredEventsSatisfied(topics, requiredEvents);
 }
 function completedViaPromise(output, promise) {
     if (!promise)