@loopover/engine 1.0.0

package/dist/miner/coding-agent-invoke.js

@@ -0,0 +1,80 @@
+// Mode-gated `CodingAgentDriver` invocation (#4313). Single call site that applies `CodingAgentExecutionMode`,
+// writes attempt-log events (#4294), and never spawns the underlying agent unless mode is `live`.
+import { codingAgentModeExecutes, } from "./coding-agent-mode.js";
+function shadowSummary(task) {
+    return `dry-run: would invoke coding agent in ${task.workingDirectory} (≤${task.maxTurns} turns, criteria ${task.acceptanceCriteriaPath})`;
+}
+/**
+ * Invoke a driver under the resolved execution mode. `paused` and `dry_run` never call `driver.run()` — see
+ * `coding-agent-mode.ts` for the dry-run tradeoff documentation.
+ */
+export async function invokeCodingAgentDriver(driver, mode, task, log) {
+    const base = { attemptId: task.attemptId, actionClass: "codegen", mode };
+    if (mode === "paused") {
+        log?.append({
+            eventType: "attempt_aborted",
+            ...base,
+            reason: "coding_agent_paused",
+            payload: { workingDirectory: task.workingDirectory },
+        });
+        return {
+            ok: false,
+            changedFiles: [],
+            summary: "coding agent paused",
+            error: "coding_agent_paused",
+        };
+    }
+    if (!codingAgentModeExecutes(mode)) {
+        log?.append({
+            eventType: "attempt_shadow",
+            ...base,
+            reason: "dry-run: would invoke coding agent without spawning underlying session",
+            payload: {
+                workingDirectory: task.workingDirectory,
+                acceptanceCriteriaPath: task.acceptanceCriteriaPath,
+                maxTurns: task.maxTurns,
+            },
+        });
+        return {
+            ok: true,
+            changedFiles: [],
+            summary: shadowSummary(task),
+            turnsUsed: 0,
+        };
+    }
+    log?.append({
+        eventType: "attempt_started",
+        ...base,
+        reason: "live coding-agent invocation",
+        payload: { workingDirectory: task.workingDirectory, maxTurns: task.maxTurns },
+    });
+    try {
+        const result = await driver.run(task);
+        log?.append({
+            eventType: result.ok ? "attempt_succeeded" : "attempt_failed",
+            ...base,
+            reason: result.summary,
+            payload: {
+                changedFiles: [...result.changedFiles],
+                turnsUsed: result.turnsUsed ?? null,
+                error: result.error ?? null,
+            },
+        });
+        return result;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "unknown error";
+        log?.append({
+            eventType: "attempt_failed",
+            ...base,
+            reason: message,
+            payload: { thrown: true },
+        });
+        return {
+            ok: false,
+            changedFiles: [],
+            summary: "coding agent invocation failed",
+            error: message,
+        };
+    }
+}

package/dist/miner/coding-agent-mode.d.ts

@@ -0,0 +1,25 @@
+/** Whether a coding-agent attempt actually spawns/queries the underlying session. */
+export type CodingAgentExecutionMode = "paused" | "dry_run" | "live";
+/** Global kill-switch for miner coding-agent invocations (`MINER_CODING_AGENT_PAUSED`). Same truthy-string
+ *  convention as `isGlobalAgentPause` (`AGENT_ACTIONS_PAUSED`). */
+export declare function isGlobalMinerCodingAgentPause(env: {
+    MINER_CODING_AGENT_PAUSED?: string | undefined;
+}): boolean;
+/** THE single gate before invoking a `CodingAgentDriver`. Precedence (safest wins): global OR per-config pause
+ *  → `paused`; else per-config dry-run → `dry_run`; else `live`. Pure. */
+export declare function resolveCodingAgentExecutionMode(input: {
+    globalPaused: boolean;
+    agentPaused?: boolean | null | undefined;
+    agentDryRun?: boolean | null | undefined;
+}): CodingAgentExecutionMode;
+/** Resolve mode from env + optional per-run overrides (mirrors `resolveAgentActionMode` call sites). */
+export declare function resolveCodingAgentModeFromConfig(config: {
+    env?: {
+        MINER_CODING_AGENT_PAUSED?: string | undefined;
+    } | undefined;
+    agentPaused?: boolean | null | undefined;
+    agentDryRun?: boolean | null | undefined;
+}): CodingAgentExecutionMode;
+/** True only for `live` — the only mode that performs a real driver `run()`. `paused` does nothing; `dry_run`
+ *  records a shadow result without spawning the underlying agent. */
+export declare function codingAgentModeExecutes(mode: CodingAgentExecutionMode): boolean;

package/dist/miner/coding-agent-mode.js

@@ -0,0 +1,43 @@
+// Coding-agent execution mode (#4313). Mirrors `AgentActionMode` at `src/settings/agent-execution.ts:23-48`:
+// three states (`paused` | `dry_run` | `live`), deny-toward-safety precedence (global/per-repo pause beats
+// dry-run beats live), and a single `codingAgentModeExecutes` boolean for callers.
+//
+// Why three states instead of a boolean? The maintainer-action layer already proved the shape: `paused` is an
+// operator kill-switch (attempt never starts), `dry_run` is an observe/shadow path (record intent without the
+// expensive/dangerous work), and `live` is the only mode that actually spawns/queries the underlying agent.
+// A boolean would collapse `paused` into `dry_run`, losing the distinction between "halt entirely" and
+// "shadow what would happen".
+//
+// Dry-run semantics for a CODING agent (#4313): at the driver invocation boundary, `dry_run` is a **pure no-op**
+// — the underlying CLI/SDK session is never spawned. Tradeoff documented here:
+//   • Chosen: never spawn (cheapest, safest, mirrors `agentActionModeExecutes` skipping GitHub mutations).
+//   • Deferred alternative: run inside an isolated worktree (#4269) but suppress commit/push/PR downstream so
+//     file edits remain inspectable — requires the worktree primitive and orchestrator gating on create-phase
+//     steps; the attempt log records `attempt_shadow` with mode=`dry_run` so either path stays auditable.
+/** Global kill-switch for miner coding-agent invocations (`MINER_CODING_AGENT_PAUSED`). Same truthy-string
+ *  convention as `isGlobalAgentPause` (`AGENT_ACTIONS_PAUSED`). */
+export function isGlobalMinerCodingAgentPause(env) {
+    return /^(1|true|yes|on)$/i.test(env.MINER_CODING_AGENT_PAUSED ?? "");
+}
+/** THE single gate before invoking a `CodingAgentDriver`. Precedence (safest wins): global OR per-config pause
+ *  → `paused`; else per-config dry-run → `dry_run`; else `live`. Pure. */
+export function resolveCodingAgentExecutionMode(input) {
+    if (input.globalPaused || input.agentPaused === true)
+        return "paused";
+    if (input.agentDryRun === true)
+        return "dry_run";
+    return "live";
+}
+/** Resolve mode from env + optional per-run overrides (mirrors `resolveAgentActionMode` call sites). */
+export function resolveCodingAgentModeFromConfig(config) {
+    return resolveCodingAgentExecutionMode({
+        globalPaused: isGlobalMinerCodingAgentPause(config.env ?? {}),
+        agentPaused: config.agentPaused,
+        agentDryRun: config.agentDryRun,
+    });
+}
+/** True only for `live` — the only mode that performs a real driver `run()`. `paused` does nothing; `dry_run`
+ *  records a shadow result without spawning the underlying agent. */
+export function codingAgentModeExecutes(mode) {
+    return mode === "live";
+}

package/dist/miner/driver-factory.d.ts

@@ -0,0 +1,82 @@
+import { type CodingAgentDriver } from "./coding-agent-driver.js";
+import { type AttemptLogSink } from "./coding-agent-invoke.js";
+import { type CodingAgentExecutionMode } from "./coding-agent-mode.js";
+import type { CodingAgentDriverResult, CodingAgentDriverTask } from "./coding-agent-driver.js";
+import { type LintGuardOptions, type LintGuardResult } from "./lint-guard.js";
+import { type CliSubprocessSpawnFn } from "./cli-subprocess-driver.js";
+import { type AgentSdkHooks, type AgentSdkQueryFn } from "./agent-sdk-driver.js";
+/** Provider names the factory resolves: the two concrete drivers from #4266/#4267 (`claude-cli`/`codex-cli`
+ *  spawn the respective CLI; `agent-sdk` runs in-process via the Agent SDK) plus the `noop` stub. All are
+ *  locally-authenticated (no API-key env requirement), mirroring how `isConfiguredSelfHostProvider` treats
+ *  `claude-code`/`codex` as always-configured. */
+export declare const CODING_AGENT_DRIVER_NAMES: readonly ["noop", "claude-cli", "codex-cli", "agent-sdk"];
+export type CodingAgentDriverName = (typeof CODING_AGENT_DRIVER_NAMES)[number];
+/** Per-provider env keys for coding-agent configuration (mirrors `SELF_HOST_REVIEWER_MODEL_ENV`). Every key
+ *  declared here is CONSUMED by `createCodingAgentDriver` below — a declared-but-unread entry is dead,
+ *  misleading config-as-code surface. Deliberately NOT declared: a max-turns key (the turn budget is task-level
+ *  input — `CodingAgentDriverTask.maxTurns` — set by the orchestrator per attempt, not per-provider config) and
+ *  an agent-sdk model key (the SDK session uses the account/CLI default; it exposes no model option on the
+ *  driver today). */
+export declare const CODING_AGENT_DRIVER_CONFIG_ENV: Readonly<Record<CodingAgentDriverName, {
+    model?: string;
+    timeoutMs?: string;
+}>>;
+/** True when `name` is a known, configured coding-agent driver. Unknown names → false (deny-by-default). */
+export declare function isConfiguredCodingAgentDriver(name: string, _env: Record<string, string | undefined>): boolean;
+export declare function resolveConfiguredCodingAgentDriverNames(env: Record<string, string | undefined>): string[];
+/** Primary-then-fallback resolution over `MINER_CODING_AGENT_PROVIDER`'s comma-separated list (the same
+ *  fallback-chain semantic `AiRunOptions.fallback` gives reviewers): the FIRST configured name wins; unknown
+ *  names are skipped (deny-by-default), and an all-unknown/empty list resolves to undefined so the caller
+ *  fails closed rather than falling through to some implicit default driver. */
+export declare function resolveFirstConfiguredCodingAgentDriverName(env: Record<string, string | undefined>): string | undefined;
+export type CreateCodingAgentDriverOptions = {
+    providerName: string;
+    env?: Record<string, string | undefined> | undefined;
+    /** Test seam — inject a fake driver instead of constructing the named provider. */
+    driver?: CodingAgentDriver | undefined;
+    /** Subprocess runner for the CLI providers (`claude-cli`/`codex-cli`). REQUIRED for those providers — the
+     *  engine package ships no default spawn, so constructing a CLI driver without one fails closed rather than
+     *  producing a driver that can never run. */
+    spawn?: CliSubprocessSpawnFn | undefined;
+    /** Optional injected `query()` loop for the `agent-sdk` provider (defaults to the real SDK import). */
+    query?: AgentSdkQueryFn | undefined;
+    /** Forwarded to the `agent-sdk` provider's session (#2343's PreToolUse interception point). */
+    hooks?: AgentSdkHooks | undefined;
+    /** Optional injected changed-file enumerator for the `agent-sdk` provider (defaults to a real `git diff`/
+     *  `git ls-files` read over the task's working directory — a test harness pointing at a non-git fake path
+     *  should inject one, same seam as `query`). */
+    listChangedFiles?: ((cwd: string) => Promise<string[]>) | undefined;
+    /** Known secret values the CLI providers strip from surfaced output, on top of the token-shape patterns. */
+    knownSecrets?: readonly string[] | undefined;
+};
+/** Resolve a concrete driver for `providerName`. Throws on unknown/unconfigured providers (fail-closed). */
+export declare function createCodingAgentDriver(options: CreateCodingAgentDriverOptions): CodingAgentDriver;
+export type RunCodingAgentAttemptOptions = {
+    providerName: string;
+    env?: Record<string, string | undefined> | undefined;
+    agentPaused?: boolean | null | undefined;
+    agentDryRun?: boolean | null | undefined;
+    task: CodingAgentDriverTask;
+    log?: AttemptLogSink | undefined;
+    driver?: CodingAgentDriver | undefined;
+    /** Provider dependencies, forwarded to `createCodingAgentDriver` (see `CreateCodingAgentDriverOptions`). */
+    spawn?: CliSubprocessSpawnFn | undefined;
+    query?: AgentSdkQueryFn | undefined;
+    hooks?: AgentSdkHooks | undefined;
+    /** Optional injected changed-file enumerator for the `agent-sdk` provider (see `CreateCodingAgentDriverOptions`). */
+    listChangedFiles?: ((cwd: string) => Promise<string[]>) | undefined;
+    knownSecrets?: readonly string[] | undefined;
+    /** When supplied, the driver result is run through the lint guard (#4276) before being returned, so a
+     *  live coding-agent edit that fails its own package's typecheck/node --check never reads as `ok: true`. */
+    lintGuard?: LintGuardOptions | undefined;
+};
+/** End-to-end entry: resolve mode from config, pick the driver, invoke under mode gating + attempt log, then
+ *  (when `lintGuard` is supplied) run the changed files through the lint guard before the caller sees the result. */
+export declare function runCodingAgentAttempt(options: RunCodingAgentAttemptOptions): Promise<{
+    mode: CodingAgentExecutionMode;
+    result: CodingAgentDriverResult & {
+        lintGuard?: LintGuardResult;
+    };
+}>;
+/** Exported for parity tests — wraps a driver without changing its behavior (identity helper). */
+export declare function createFakeCodingAgentDriverForFactory(): CodingAgentDriver;

package/dist/miner/driver-factory.js

@@ -0,0 +1,169 @@
+// CodingAgentDriver factory + provider-style config resolution (#4289). Mirrors `src/selfhost/ai-config.ts:41-74`:
+// parse a comma-separated provider list, validate each name against what is actually configured, deny-by-default
+// on unknown/unconfigured names, and expose a model/effort config map analogous to `SELF_HOST_REVIEWER_MODEL_ENV`.
+import { createFakeCodingAgentDriver, createNoopCodingAgentDriver, } from "./coding-agent-driver.js";
+import { invokeCodingAgentDriver, } from "./coding-agent-invoke.js";
+import { codingAgentModeExecutes, resolveCodingAgentModeFromConfig, } from "./coding-agent-mode.js";
+import { guardCodingAgentDriverResult } from "./lint-guard.js";
+import { createCliSubprocessCodingAgentDriver, defaultClaudeCliArgs, defaultCodexCliArgs, } from "./cli-subprocess-driver.js";
+import { createAgentSdkCodingAgentDriver, } from "./agent-sdk-driver.js";
+/** Provider names the factory resolves: the two concrete drivers from #4266/#4267 (`claude-cli`/`codex-cli`
+ *  spawn the respective CLI; `agent-sdk` runs in-process via the Agent SDK) plus the `noop` stub. All are
+ *  locally-authenticated (no API-key env requirement), mirroring how `isConfiguredSelfHostProvider` treats
+ *  `claude-code`/`codex` as always-configured. */
+export const CODING_AGENT_DRIVER_NAMES = Object.freeze(["noop", "claude-cli", "codex-cli", "agent-sdk"]);
+/** Per-provider env keys for coding-agent configuration (mirrors `SELF_HOST_REVIEWER_MODEL_ENV`). Every key
+ *  declared here is CONSUMED by `createCodingAgentDriver` below — a declared-but-unread entry is dead,
+ *  misleading config-as-code surface. Deliberately NOT declared: a max-turns key (the turn budget is task-level
+ *  input — `CodingAgentDriverTask.maxTurns` — set by the orchestrator per attempt, not per-provider config) and
+ *  an agent-sdk model key (the SDK session uses the account/CLI default; it exposes no model option on the
+ *  driver today). */
+export const CODING_AGENT_DRIVER_CONFIG_ENV = Object.freeze({
+    noop: {},
+    "claude-cli": { model: "MINER_CODING_AGENT_CLAUDE_MODEL", timeoutMs: "MINER_CODING_AGENT_TIMEOUT_MS" },
+    "codex-cli": { model: "MINER_CODING_AGENT_CODEX_MODEL", timeoutMs: "MINER_CODING_AGENT_TIMEOUT_MS" },
+    "agent-sdk": {},
+});
+/** `firstConfigured` (src/selfhost/ai.ts:117-134) pattern: a set-and-non-empty env value, else undefined. */
+function firstConfiguredEnvValue(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : undefined;
+}
+/** Positive-integer env parse for the CLI wall-clock ceiling; anything else defers to the driver default. */
+function configuredTimeoutMs(env) {
+    const raw = Number(firstConfiguredEnvValue(env.MINER_CODING_AGENT_TIMEOUT_MS));
+    return Number.isFinite(raw) && Number.isInteger(raw) && raw > 0 ? raw : undefined;
+}
+function parseDriverNames(env) {
+    return (env.MINER_CODING_AGENT_PROVIDER ?? "")
+        .split(",")
+        .map((value) => value.trim().toLowerCase())
+        .filter(Boolean);
+}
+/** True when `name` is a known, configured coding-agent driver. Unknown names → false (deny-by-default). */
+export function isConfiguredCodingAgentDriver(name, _env) {
+    switch (name) {
+        case "noop":
+        case "claude-cli":
+        case "codex-cli":
+        case "agent-sdk":
+            return true;
+        default:
+            return false;
+    }
+}
+export function resolveConfiguredCodingAgentDriverNames(env) {
+    return parseDriverNames(env).filter((name) => isConfiguredCodingAgentDriver(name, env));
+}
+/** Primary-then-fallback resolution over `MINER_CODING_AGENT_PROVIDER`'s comma-separated list (the same
+ *  fallback-chain semantic `AiRunOptions.fallback` gives reviewers): the FIRST configured name wins; unknown
+ *  names are skipped (deny-by-default), and an all-unknown/empty list resolves to undefined so the caller
+ *  fails closed rather than falling through to some implicit default driver. */
+export function resolveFirstConfiguredCodingAgentDriverName(env) {
+    return resolveConfiguredCodingAgentDriverNames(env)[0];
+}
+/** Build a CLI provider's argv: the driver's own real default argv contract, with the CONFIGURED model
+ *  flag inserted at the RIGHT position for that command — this is where that declared config is actually
+ *  consumed. claude's `--model` is a top-level flag (prefixed before everything else is fine); codex's
+ *  `-m`/`--model` is scoped to the `exec` subcommand (per `codex exec --help`) and must be inserted AFTER
+ *  the leading `"exec"` token, not before it — a single shared prefix-everything scheme would silently
+ *  misparse for codex. */
+function buildCliArgsWithConfiguredModel(command, model) {
+    if (model === undefined)
+        return undefined;
+    if (command === "claude") {
+        return (task) => ["--model", model, ...defaultClaudeCliArgs(task)];
+    }
+    return (task) => {
+        const [subcommand, ...rest] = defaultCodexCliArgs(task);
+        return [subcommand, "--model", model, ...rest];
+    };
+}
+function createCliProvider(command, modelEnvKey, options, env) {
+    if (!options.spawn) {
+        // Fail-closed (resolveAutonomy's deny-by-default precedent): a CLI provider without a spawn dependency is
+        // unconfigured in the way that matters — never hand back a driver whose every run() would throw.
+        throw new Error(`unconfigured_coding_agent_driver_missing_spawn:${command}-cli`);
+    }
+    if (options.hooks !== undefined) {
+        // CLI subprocess providers have no hook-registration surface. If a caller supplied house-rule hooks, treating
+        // them as "best effort" would silently run prompt-influenced local code without the policy the caller asked
+        // for, so fail closed until a CLI-native enforcement layer exists.
+        throw new Error(`unsupported_coding_agent_driver_hooks:${command}-cli`);
+    }
+    const model = firstConfiguredEnvValue(env[modelEnvKey]);
+    const timeoutMs = configuredTimeoutMs(env);
+    const buildArgs = buildCliArgsWithConfiguredModel(command, model);
+    return createCliSubprocessCodingAgentDriver({
+        command,
+        spawn: options.spawn,
+        parentEnv: env,
+        ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+        ...(buildArgs !== undefined ? { buildArgs } : {}),
+        ...(options.knownSecrets !== undefined ? { knownSecrets: options.knownSecrets } : {}),
+    });
+}
+/** Resolve a concrete driver for `providerName`. Throws on unknown/unconfigured providers (fail-closed). */
+export function createCodingAgentDriver(options) {
+    if (options.driver)
+        return options.driver;
+    const name = options.providerName.trim().toLowerCase();
+    const env = options.env ?? {};
+    if (!isConfiguredCodingAgentDriver(name, env)) {
+        throw new Error(`unconfigured_coding_agent_driver:${name}`);
+    }
+    switch (name) {
+        case "noop":
+            return createNoopCodingAgentDriver();
+        case "claude-cli":
+            return createCliProvider("claude", "MINER_CODING_AGENT_CLAUDE_MODEL", options, env);
+        case "codex-cli":
+            return createCliProvider("codex", "MINER_CODING_AGENT_CODEX_MODEL", options, env);
+        case "agent-sdk":
+            // No model/timeout config today — the SDK session uses the account default; hooks/query are optional.
+            return createAgentSdkCodingAgentDriver({
+                ...(options.query !== undefined ? { query: options.query } : {}),
+                ...(options.hooks !== undefined ? { hooks: options.hooks } : {}),
+                ...(options.listChangedFiles !== undefined ? { listChangedFiles: options.listChangedFiles } : {}),
+            });
+        /* v8 ignore next 2 -- isConfiguredCodingAgentDriver already rejects unknown names before this switch. */
+        default:
+            throw new Error(`unconfigured_coding_agent_driver:${name}`);
+    }
+}
+function resolveDriverForAttempt(options, mode) {
+    if (options.driver)
+        return options.driver;
+    // Dry-run/paused attempts never call `driver.run()` (see coding-agent-driver.md lifecycle). Constructing a
+    // CLI provider here would require spawn/query deps even though they would never be used — use the noop stub
+    // as a stand-in so shadow/paused attempts stay dependency-free (#4289 / gate fix for #4593).
+    if (!codingAgentModeExecutes(mode))
+        return createNoopCodingAgentDriver();
+    return createCodingAgentDriver({
+        providerName: options.providerName,
+        env: options.env,
+        spawn: options.spawn,
+        query: options.query,
+        hooks: options.hooks,
+        listChangedFiles: options.listChangedFiles,
+        knownSecrets: options.knownSecrets,
+    });
+}
+/** End-to-end entry: resolve mode from config, pick the driver, invoke under mode gating + attempt log, then
+ *  (when `lintGuard` is supplied) run the changed files through the lint guard before the caller sees the result. */
+export async function runCodingAgentAttempt(options) {
+    const mode = resolveCodingAgentModeFromConfig({
+        env: options.env,
+        agentPaused: options.agentPaused,
+        agentDryRun: options.agentDryRun,
+    });
+    const driver = resolveDriverForAttempt(options, mode);
+    const result = await invokeCodingAgentDriver(driver, mode, options.task, options.log);
+    if (!options.lintGuard)
+        return { mode, result };
+    return { mode, result: await guardCodingAgentDriverResult(result, options.lintGuard) };
+}
+/** Exported for parity tests — wraps a driver without changing its behavior (identity helper). */
+export function createFakeCodingAgentDriverForFactory() {
+    return createFakeCodingAgentDriver();
+}

package/dist/miner/harness-submission-trigger.d.ts

@@ -0,0 +1,37 @@
+import type { MinerKillSwitchScope } from "../governor/kill-switch.js";
+import type { HandoffPacket } from "./iterate-policy.js";
+import type { SelfReviewSlopBand } from "./self-review-adapter.js";
+import { type SubmissionGateMode } from "./submission-gate.js";
+export declare const DEFAULT_MAX_CONSECUTIVE_GATE_BLOCKS = 3;
+export type HarnessSubmissionTriggerCandidate = {
+    /** Forwarded to `shouldSubmit`'s own kill-switch check (#2339) -- this function does not ALSO short-circuit
+     *  on it separately (that would be a second, duplicated check, exactly what #2339's "single shared helper,
+     *  not duplicated per call site" deliverable warns against); `shouldSubmit` is always still called (the
+     *  circuit breaker above is the only thing that skips it), and its own kill-switch guard covers this. */
+    killSwitchScope: MinerKillSwitchScope;
+    handoffPacket: HandoffPacket;
+    slopThreshold: SelfReviewSlopBand;
+    mode: SubmissionGateMode;
+    /** Caller-computed count of CONSECUTIVE `allow: false` submission-gate decisions so far this session,
+     *  ending with (and NOT including) this candidate's own about-to-be-computed decision. The caller owns this
+     *  tally (mirrors #2338's caller-supplied `consecutiveDisengagements`); a `true` decision anywhere resets it
+     *  to 0 for the caller's NEXT candidate. */
+    consecutiveGateBlocks: number;
+    maxConsecutiveGateBlocks?: number | undefined;
+};
+export type HarnessSubmissionTriggerDecision = {
+    allow: boolean;
+    reasons: string[];
+    /** True only when the SESSION-LEVEL circuit breaker (not a normal per-candidate block) is what stopped this
+     *  decision -- the caller's own driving loop should treat this as "pause the run entirely pending human
+     *  review," distinct from an ordinary `allow: false` a later, different candidate might still clear. */
+    circuitBreakerTripped: boolean;
+};
+/**
+ * THE final gate before a real call site may build the `open_pr` local-write spec from a passing
+ * `HandoffPacket`. Pure; identical inputs always yield the identical decision. Checks the session-level
+ * circuit breaker FIRST (never consults `shouldSubmit` once tripped), then re-checks `shouldSubmit`'s own
+ * predicted-gate-pass + slop-under-threshold signals against the handoff's own verdict -- defense in depth,
+ * not a blind trust of the fact that a handoff happened at all.
+ */
+export declare function evaluateHarnessSubmissionTrigger(candidate: HarnessSubmissionTriggerCandidate): HarnessSubmissionTriggerDecision;

package/dist/miner/harness-submission-trigger.js

@@ -0,0 +1,46 @@
+// Harness submission-gate wiring (#2337): connects the gated-submission decision function (`shouldSubmit`,
+// submission-gate.ts, #2336) to the ACTUAL driving loop's own handoff signal -- iterate-loop.ts's (#2333)
+// `HandoffPacket`, the exact object produced the moment a real run's self-review reaches a clean predicted-gate
+// pass. This is the live actuation wiring itself: the trigger surface the safety-tier system reserves for
+// maintainer review, since a bug here means an autonomous write happens when it should not have.
+//
+// WHAT THIS DOES NOT DO: build or invoke the actual `open_pr` local-write spec (`buildOpenPrSpec`,
+// `src/mcp/local-write-tools.ts`) -- that lives in the private root `src/` tree, unreachable from this
+// portable package for the same cross-package-boundary reason self-review-adapter.ts's slop injection exists
+// (#2334's own module doc comment). This function's OUTPUT (`allow: true`) is the gate a real call site
+// (root-side server/CLI integration, wired in a later issue) consults before it builds that spec itself --
+// mirrors #2336's own "gated exclusively through this function" scoping.
+//
+// THE SESSION-LEVEL CIRCUIT BREAKER: distinct from `shouldSubmit`'s own per-candidate signal checks
+// (predicted-gate pass, slop-under-threshold), this issue's own deliverable calls for "N consecutive
+// submission-gate allow:false decisions in one session pauses the run entirely pending human review, never
+// silently loops trying to force a pass." Checked FIRST, before ever consulting `shouldSubmit` -- once tripped,
+// no candidate can un-trip it (that requires a human clearing the session's own consecutive-block tally),
+// unlike a per-candidate block which a later, different candidate can clear on its own merits.
+import { shouldSubmit } from "./submission-gate.js";
+export const DEFAULT_MAX_CONSECUTIVE_GATE_BLOCKS = 3;
+/**
+ * THE final gate before a real call site may build the `open_pr` local-write spec from a passing
+ * `HandoffPacket`. Pure; identical inputs always yield the identical decision. Checks the session-level
+ * circuit breaker FIRST (never consults `shouldSubmit` once tripped), then re-checks `shouldSubmit`'s own
+ * predicted-gate-pass + slop-under-threshold signals against the handoff's own verdict -- defense in depth,
+ * not a blind trust of the fact that a handoff happened at all.
+ */
+export function evaluateHarnessSubmissionTrigger(candidate) {
+    const maxConsecutiveGateBlocks = candidate.maxConsecutiveGateBlocks ?? DEFAULT_MAX_CONSECUTIVE_GATE_BLOCKS;
+    if (candidate.consecutiveGateBlocks >= maxConsecutiveGateBlocks) {
+        return {
+            allow: false,
+            circuitBreakerTripped: true,
+            reasons: [`circuit_breaker_tripped_after_consecutive_blocks:${candidate.consecutiveGateBlocks}>=${maxConsecutiveGateBlocks}`],
+        };
+    }
+    const gateDecision = shouldSubmit({
+        killSwitchScope: candidate.killSwitchScope,
+        predictedGateVerdict: candidate.handoffPacket.selfReviewVerdict.predictedGateVerdict,
+        slopAssessment: candidate.handoffPacket.selfReviewVerdict.slopAssessment,
+        slopThreshold: candidate.slopThreshold,
+        mode: candidate.mode,
+    });
+    return { allow: gateDecision.allow, reasons: gateDecision.reasons, circuitBreakerTripped: false };
+}

package/dist/miner/iterate-loop.d.ts

@@ -0,0 +1,97 @@
+import type { CodingAgentDriver, CodingAgentDriverResult } from "./coding-agent-driver.js";
+import { type CodingAgentExecutionMode } from "./coding-agent-mode.js";
+import type { AttemptLogEvent } from "./attempt-log.js";
+import { type SelfReviewAdapterDeps, type SelfReviewContext } from "./self-review-adapter.js";
+import { type IterateLoopDecision, type HandoffPacket } from "./iterate-policy.js";
+import { type AttemptBudget, type AttemptBudgetAxis, type AttemptMeterTotals } from "./attempt-metering.js";
+/** Everything one call to {@link runIterateLoop} needs, aside from the injected {@link IterateLoopDeps}.
+ *  Identity/context fields mirror self-review-adapter.ts's `AttemptDiffState`/`SelfReviewContext` exactly --
+ *  the caller assembles these from whatever Phase 2 plan/acceptance-criteria packet exists; that packet's
+ *  exact combined shape is explicitly out of scope for this issue. */
+export type IterateLoopInput = {
+    attemptId: string;
+    workingDirectory: string;
+    acceptanceCriteriaPath: string;
+    instructions: string;
+    /** Resolved by the caller (e.g. the Governor chokepoint / action-mode resolution, #2340/#2342) -- this loop
+     *  does not re-derive execution mode itself, only records whatever mode it is told. */
+    mode: CodingAgentExecutionMode;
+    /** Hard ceiling on iteration count, enforced every iteration via iterate-policy.ts. `<= 0` abandons before
+     *  the first driver invocation. */
+    maxIterations: number;
+    /** Per-iteration turn budget, passed through to each `CodingAgentDriverTask`. */
+    maxTurnsPerIteration: number;
+    /** Optional cumulative budget ceiling(s), evaluated every iteration against the real running totals
+     *  (attempt-metering.ts's `AttemptMeterTotals`, #5395). Omitted means no additional ceiling beyond what
+     *  `maxIterations * maxTurnsPerIteration` already implies. A breach on any axis (turns/costUsd/wallClockMs
+     *  -- tokens is never real-tracked today) is a HARD, unconditional stop: checked and abandoned on BEFORE
+     *  self-review even runs, so a same-iteration pass can never bypass the ceiling (this is deliberately NOT
+     *  routed through iterate-policy.ts's `costCeilingReached` field, whose own precedence checks a self-review
+     *  pass first -- see the loop body's own comment at the check site for why that ordering doesn't fit a hard
+     *  budget ceiling). */
+    budget?: AttemptBudget | undefined;
+    repoFullName: string;
+    contributorLogin: string;
+    title: string;
+    body?: string | undefined;
+    labels?: string[] | undefined;
+    linkedIssues?: number[] | undefined;
+    authorAssociation?: string | undefined;
+    /** Optional branch ref for the attempt's worktree, threaded through to a passing {@link HandoffPacket}
+     *  unchanged -- this loop does not itself manage worktrees/branches (worktree-allocator.ts's job). */
+    branchRef?: string | undefined;
+    /** Repo-level self-review context (manifest, repo record, issues, pull requests, ...) -- passed through to
+     *  `runSelfReview` unchanged every iteration. */
+    reviewContext: SelfReviewContext;
+    /** True when the target repo (or this contributor's history with it) has signaled it does not want
+     *  automated contributions -- resolved by the caller (AI-policy-map / rejection-state-machine), consumed
+     *  as-is. See iterate-policy.ts's own `IterationState.rejectionSignaled` doc comment. */
+    rejectionSignaled: boolean;
+};
+export type IterateLoopDeps = {
+    driver: CodingAgentDriver;
+    runSlopAssessment: SelfReviewAdapterDeps["runSlopAssessment"];
+    appendAttemptLogEvent: (event: AttemptLogEvent) => void;
+    /** Injected clock for real per-iteration wall-clock measurement (#5395), mirroring this package's own
+     *  injected-dependency discipline elsewhere (never a hardcoded `Date.now()` a test can't control). Defaults
+     *  to the real `Date.now` when omitted. */
+    nowMs?: (() => number) | undefined;
+};
+/** The terminal outcomes a full loop run can end in -- never `"continue"`, which is only ever a per-iteration,
+ *  non-terminal signal. */
+export type IterateLoopOutcome = "handoff" | "abandon";
+export type IterateLoopIterationRecord = {
+    iterationNumber: number;
+    driverResult: CodingAgentDriverResult;
+    decision: IterateLoopDecision;
+};
+export type IterateLoopResult = {
+    outcome: IterateLoopOutcome;
+    finalDecision: IterateLoopDecision;
+    /** Count of iterations that actually invoked the driver -- `0` for the `maxIterations <= 0` immediate-abandon
+     *  case, since the driver is never invoked there. */
+    iterationsUsed: number;
+    /** Cumulative `turnsUsed` summed across every iteration that ran. */
+    totalTurnsUsed: number;
+    /** Cumulative real dollar cost summed across every iteration that ran, from each iteration's
+     *  `CodingAgentDriverResult.costUsd`. Only the `agent-sdk` provider reports this today (the CLI-subprocess
+     *  providers report no cost signal) -- always `0` for a provider that never reports one, never fabricated. */
+    totalCostUsd: number;
+    /** The real accumulated {@link AttemptMeterTotals} across every iteration that ran (attempt-metering.ts,
+     *  #5395) -- a superset of `totalTurnsUsed`/`totalCostUsd` above that also carries `wallClockMs` (real,
+     *  measured around each driver invocation) and `tokens` (always 0 today -- no driver reports a real token
+     *  count, an honest absence rather than a fabricated number). */
+    finalMeterTotals: AttemptMeterTotals;
+    /** The budget axes breached at the point this attempt abandoned, when `input.budget` was set and at least
+     *  one axis was at/over its ceiling -- empty when no budget was configured or none breached. */
+    budgetBreaches: AttemptBudgetAxis[];
+    iterations: readonly IterateLoopIterationRecord[];
+    /** Populated only when `outcome === "handoff"`. */
+    handoffPacket?: HandoffPacket | undefined;
+};
+/**
+ * Thin wrapper over {@link runIterateLoopCore} that attaches the real accumulated
+ * {@link AttemptMeterTotals}/breached axes (#5395) once, at this single always-reached return point -- see
+ * {@link IterateLoopCoreResult}'s own doc comment for why the core itself doesn't carry these fields.
+ */
+export declare function runIterateLoop(input: IterateLoopInput, deps: IterateLoopDeps): Promise<IterateLoopResult>;