@loopover/engine 1.0.0

package/dist/miner/iterate-loop.js

@@ -0,0 +1,278 @@
+// Local create->score->self-review->decide iterate-loop orchestrator (#2333): the actual autonomous control
+// flow Phase 3 exists to build. Repeatedly invokes a `CodingAgentDriver` (coding-agent-driver.ts), self-reviews
+// the resulting diff against the byte-identical predicted-gate target (self-review-adapter.ts, #2334), and
+// consults the pure policy (iterate-policy.ts, #2335) to decide -- autonomously, no human in the loop at this
+// stage -- whether to keep iterating, hand off to Phase 4 submission, or abandon.
+//
+// TAGGED maintainer (not contributor) per the phase brief: this orchestration control flow is the precise
+// chokepoint the fixed architecture skeleton's safety-tier system reserves for the owner -- it is the trigger
+// surface for "does the system keep trying, or does it eventually open a PR" without a human approving each
+// step, and is adjacent to the #1 slop-at-scale strategic risk (an autonomous fleet maximizing gate-pass rate
+// can mass-produce gate-passing-but-low-value PRs).
+//
+// FAIL CLOSED ON AMBIGUITY: a driver run that does not complete successfully, or a self-review call that
+// itself throws, is treated identically to a `SelfReviewOutcome` of `"ambiguous"` -- iterate-policy.ts's own
+// precedence then abandons rather than optimistically continuing or handing off. The loop never fabricates a
+// "pass" from anything other than a genuinely successful `runSelfReview` call.
+//
+// BOUNDED INSIDE THE LOOP: both the iteration ceiling (`input.maxIterations`) and the optional cumulative
+// budget (`input.budget`, evaluated every iteration via attempt-metering.ts's `accumulateAttemptUsage`/
+// `evaluateAttemptBudget` against real per-iteration turns/costUsd/wallClockMs -- tokens stays an honest 0,
+// no driver reports a real token count today, #5395) are enforced here every iteration -- not left to an
+// external caller to remember, and not just capped after the fact between loop cycles (loop-cli.js's own
+// governor cap usage). A `maxIterations <= 0` input abandons immediately, before ever invoking the driver.
+//
+// AUDITABLE: every iteration's decision (continue / handoff / abandon) is recorded via the injected
+// `appendAttemptLogEvent` dependency (attempt-log.ts's normalized event shape) before this function returns
+// control to its caller for that iteration -- the decision trail survives independently of this function's own
+// return value. A logging failure never alters the loop's decision (mirrors the governor-ledger and
+// pretooluse-hook append-failure handling elsewhere in this package).
+import { codingAgentModeExecutes } from "./coding-agent-mode.js";
+import { invokeCodingAgentDriver } from "./coding-agent-invoke.js";
+import { runSelfReview } from "./self-review-adapter.js";
+import { decideNextActionWithReason, deriveSelfReviewOutcome } from "./iterate-policy.js";
+import { accumulateAttemptUsage, evaluateAttemptBudget } from "./attempt-metering.js";
+function buildAttemptDiffState(input, driverResult) {
+    return {
+        repoFullName: input.repoFullName,
+        contributorLogin: input.contributorLogin,
+        title: input.title,
+        ...(input.body !== undefined ? { body: input.body } : {}),
+        ...(input.labels !== undefined ? { labels: input.labels } : {}),
+        ...(input.linkedIssues !== undefined ? { linkedIssues: input.linkedIssues } : {}),
+        ...(input.authorAssociation !== undefined ? { authorAssociation: input.authorAssociation } : {}),
+        changedFiles: driverResult.changedFiles.map((path) => ({ path })),
+    };
+}
+/** Turn one iteration's driver result into a policy-ready {@link SelfReviewOutcome}. A driver run that did not
+ *  complete successfully, or a `runSelfReview` call that itself throws, both become `"ambiguous"` -- this loop
+ *  never fabricates a pass/fail from anything other than a genuinely successful self-review call. */
+function evaluateSelfReviewOutcome(input, driverResult, deps) {
+    if (!driverResult.ok) {
+        return {
+            outcome: { kind: "ambiguous", reason: `driver run did not complete successfully${driverResult.error ? `: ${driverResult.error}` : "."}` },
+        };
+    }
+    try {
+        const verdict = runSelfReview(buildAttemptDiffState(input, driverResult), input.reviewContext, { runSlopAssessment: deps.runSlopAssessment });
+        return { outcome: deriveSelfReviewOutcome(verdict), verdict };
+    }
+    catch (error) {
+        return { outcome: { kind: "ambiguous", reason: `self_review_error: ${error instanceof Error ? error.message : String(error)}` } };
+    }
+}
+/** A thrown driver error is normalized into the same `{ ok: false }` shape a driver returning gracefully would
+ *  produce, so {@link evaluateSelfReviewOutcome} has exactly one failure path to handle, not two. Non-live modes
+ *  are also resolved here, at the driver boundary, so paused/dry-run attempts never spawn the underlying agent. */
+async function runDriverSafely(input, deps, task) {
+    if (!codingAgentModeExecutes(input.mode)) {
+        return invokeCodingAgentDriver(deps.driver, input.mode, task, {
+            append: (event) => safeAppendAttemptLogEvent(deps, event),
+        });
+    }
+    try {
+        return await deps.driver.run(task);
+    }
+    catch (error) {
+        return { ok: false, changedFiles: [], summary: "", error: `driver_threw: ${error instanceof Error ? error.message : String(error)}` };
+    }
+}
+function attemptLogEventTypeForDecision(decision) {
+    if (decision.action === "continue")
+        return "attempt_tool_edit";
+    if (decision.action === "handoff")
+        return "attempt_succeeded";
+    // abandon: a deliberate early disengagement (rejection signaled, or the self-review itself was inconclusive)
+    // reads as aborted; a genuine failure to converge (ceiling reached, or stuck with no progress) reads as
+    // failed. Both are still `action: "abandon"` in the decision itself -- this is only a coarser attempt-log
+    // classification layered on top, for the fixed six-value ATTEMPT_LOG_EVENT_TYPES vocabulary.
+    if (decision.abandonReason === "rejection_signaled" || decision.abandonReason === "self_review_ambiguous")
+        return "attempt_aborted";
+    return "attempt_failed";
+}
+/** A logging failure must never crash the loop or alter its decision -- mirrors the governor-ledger and
+ *  pretooluse-hook append-failure handling elsewhere in this package. */
+function safeAppendAttemptLogEvent(deps, event) {
+    try {
+        deps.appendAttemptLogEvent(event);
+    }
+    catch {
+        // Deliberately swallowed -- see doc comment above.
+    }
+}
+function logDecision(input, deps, iterationNumber, decision, budgetBreaches) {
+    safeAppendAttemptLogEvent(deps, {
+        eventType: attemptLogEventTypeForDecision(decision),
+        attemptId: input.attemptId,
+        actionClass: "iterate_loop",
+        mode: input.mode,
+        reason: decision.reason,
+        payload: {
+            iterationNumber,
+            action: decision.action,
+            ...(decision.abandonReason !== undefined ? { abandonReason: decision.abandonReason } : {}),
+            // Which real axis (or axes) breached, on the hard-budget-ceiling abandon path (#5395, checked directly
+            // in the loop body before self-review even runs -- see that check site's own comment) -- an operator
+            // reading the attempt log back otherwise has no way to see which axis actually tripped.
+            ...(budgetBreaches.length > 0 ? { budgetBreaches } : {}),
+        },
+    });
+}
+/**
+ * Extract the blocker codes to carry into the next iteration's no-progress comparison. Only ever called after
+ * `decideNextActionWithReason` has returned `"continue"` for this exact `outcome` -- that function's own
+ * precedence ladder short-circuits BOTH the `"ambiguous"` and `"pass"` variants (to abandon and handoff
+ * respectively) before ever reaching its `"continue"` fallthrough, so `outcome.kind === "fail"` is guaranteed
+ * whenever this is reached from the real call site below, not just the common case.
+ */
+function blockerCodesFromContinuingOutcome(outcome) {
+    if (outcome.kind === "fail")
+        return outcome.blockerCodes;
+    /* v8 ignore next -- unreachable: see this function's own doc comment above. */
+    return [];
+}
+function buildHandoffPacket(input, verdict, driverResult) {
+    return {
+        worktreePath: input.workingDirectory,
+        ...(input.branchRef !== undefined ? { branchRef: input.branchRef } : {}),
+        diffSummary: driverResult.summary,
+        selfReviewVerdict: verdict,
+        attemptLogReference: input.attemptId,
+    };
+}
+const ZERO_METER_TOTALS = { tokens: 0, turns: 0, wallClockMs: 0, costUsd: 0 };
+function immediateAbandonNoIterationsPermitted(input, deps) {
+    const decision = {
+        action: "abandon",
+        abandonReason: "max_iterations_reached",
+        reason: `maxIterations (${input.maxIterations}) permits no iterations; abandoning without invoking the driver.`,
+    };
+    safeAppendAttemptLogEvent(deps, {
+        eventType: "attempt_aborted",
+        attemptId: input.attemptId,
+        actionClass: "iterate_loop",
+        mode: input.mode,
+        reason: decision.reason,
+        payload: { iterationNumber: 0, action: decision.action, abandonReason: decision.abandonReason },
+    });
+    return { outcome: "abandon", finalDecision: decision, iterationsUsed: 0, totalTurnsUsed: 0, totalCostUsd: 0, iterations: [] };
+}
+/**
+ * Run the full create->score->self-review->decide loop for one attempt, iteration by iteration, until
+ * iterate-policy.ts's {@link decideNextActionWithReason} reaches a terminal `"handoff"` or `"abandon"`.
+ *
+ * Every iteration: invoke the driver, self-review the resulting diff (never fabricating a pass from a failed
+ * or errored driver/self-review run), consult the policy with the running iteration/cost/no-progress state,
+ * and record the decision via the attempt-log. `"continue"` decisions loop again; `"handoff"`/`"abandon"`
+ * return immediately. See {@link IterateLoopCoreResult}'s own doc comment for why this doesn't carry
+ * `finalMeterTotals`/`budgetBreaches` itself -- {@link runIterateLoop} attaches those.
+ */
+async function runIterateLoopCore(input, deps, tracker) {
+    // Truncated toward zero rather than used as-is: a fractional maxIterations (a caller bug -- "how many times
+    // to run a coding agent" has no fractional meaning) would otherwise let this loop's own `for` bound and
+    // iterate-policy.ts's `iterationNumber >= maxIterations` ceiling check disagree by less than one iteration
+    // (e.g. 2.5 lets the `for` loop run a 3rd time that the ceiling check, comparing against 2.5, would not yet
+    // reject), silently permitting one extra iteration beyond the caller's intent. Normalizing once here keeps
+    // both checks watching the exact same integer ceiling.
+    const maxIterations = Math.max(0, Math.trunc(input.maxIterations));
+    if (maxIterations <= 0)
+        return immediateAbandonNoIterationsPermitted(input, deps);
+    safeAppendAttemptLogEvent(deps, {
+        eventType: "attempt_started",
+        attemptId: input.attemptId,
+        actionClass: "iterate_loop",
+        mode: input.mode,
+        reason: "iterate_loop_started",
+        payload: { maxIterations, maxTurnsPerIteration: input.maxTurnsPerIteration },
+    });
+    const nowMs = deps.nowMs ?? Date.now;
+    const iterations = [];
+    let previousBlockerCodes = null;
+    let totalTurnsUsed = 0;
+    let totalCostUsd = 0;
+    for (let iterationNumber = 1; iterationNumber <= maxIterations; iterationNumber += 1) {
+        const iterationStartMs = nowMs();
+        const driverResult = await runDriverSafely(input, deps, {
+            attemptId: input.attemptId,
+            workingDirectory: input.workingDirectory,
+            acceptanceCriteriaPath: input.acceptanceCriteriaPath,
+            instructions: input.instructions,
+            maxTurns: input.maxTurnsPerIteration,
+        });
+        const iterationElapsedMs = Math.max(0, nowMs() - iterationStartMs);
+        totalTurnsUsed += driverResult.turnsUsed ?? 0;
+        totalCostUsd += driverResult.costUsd ?? 0;
+        // tokens stays an honest 0: no CodingAgentDriver reports a real per-iteration token count today (#5395) --
+        // an absence, never a fabricated number, matching this package's costUsd discipline elsewhere.
+        tracker.totals = accumulateAttemptUsage(tracker.totals, {
+            tokens: 0,
+            turns: driverResult.turnsUsed ?? 0,
+            wallClockMs: iterationElapsedMs,
+            costUsd: driverResult.costUsd ?? 0,
+        });
+        const budgetVerdict = input.budget !== undefined ? evaluateAttemptBudget(tracker.totals, input.budget) : undefined;
+        tracker.breaches = budgetVerdict?.breaches ?? [];
+        // A reached budget ceiling is a HARD, unconditional stop -- checked and, if breached, acted on BEFORE
+        // self-review even runs, so a same-iteration pass can never bypass it. The spend/turns/time on this
+        // iteration are sunk either way (the driver already ran), but handing off anyway would let a single
+        // over-budget iteration silently defeat the entire point of wiring a ceiling in (#5395's own mid-attempt
+        // abort goal) -- so this abandons regardless of what this iteration's own result looks like.
+        if (budgetVerdict !== undefined && !budgetVerdict.withinBudget) {
+            const decision = {
+                action: "abandon",
+                abandonReason: "cost_ceiling_reached",
+                reason: `Reached the attempt's budget ceiling (${tracker.breaches.join(", ")}) on iteration ${iterationNumber}; abandoning regardless of this iteration's own result.`,
+            };
+            logDecision(input, deps, iterationNumber, decision, tracker.breaches);
+            iterations.push({ iterationNumber, driverResult, decision });
+            return { outcome: "abandon", finalDecision: decision, iterationsUsed: iterationNumber, totalTurnsUsed, totalCostUsd, iterations };
+        }
+        const { outcome: selfReview, verdict } = evaluateSelfReviewOutcome(input, driverResult, deps);
+        const state = {
+            iterationNumber,
+            maxIterations,
+            selfReview,
+            previousBlockerCodes,
+            rejectionSignaled: input.rejectionSignaled,
+        };
+        const decision = decideNextActionWithReason(state);
+        logDecision(input, deps, iterationNumber, decision, []);
+        iterations.push({ iterationNumber, driverResult, decision });
+        if (decision.action === "handoff") {
+            // Guaranteed defined: decideNextActionWithReason only reaches `"handoff"` from `selfReview.kind ===
+            // "pass"`, which evaluateSelfReviewOutcome only ever returns alongside a real, successfully computed
+            // verdict (never from the ambiguous/driver-failure path).
+            return {
+                outcome: "handoff",
+                finalDecision: decision,
+                iterationsUsed: iterationNumber,
+                totalTurnsUsed,
+                totalCostUsd,
+                iterations,
+                handoffPacket: buildHandoffPacket(input, verdict, driverResult),
+            };
+        }
+        if (decision.action === "abandon") {
+            return { outcome: "abandon", finalDecision: decision, iterationsUsed: iterationNumber, totalTurnsUsed, totalCostUsd, iterations };
+        }
+        previousBlockerCodes = blockerCodesFromContinuingOutcome(selfReview);
+    }
+    /* v8 ignore next 8 -- unreachable in practice: decideNextActionWithReason's own `iterationNumber >=
+     * maxIterations` check guarantees an abandon by the time iterationNumber reaches the (now-integer, per the
+     * truncation above) maxIterations ceiling inside the loop above, so the for-loop above always returns.
+     * Retained as an explicit fail-closed fallback rather than an implicit `undefined` return, consistent with
+     * this package's fail-closed discipline, in case a future edit to the precedence ladder ever removes that
+     * guarantee. */
+    const fallbackDecision = { action: "abandon", abandonReason: "max_iterations_reached", reason: "Iterate loop exhausted its iteration budget." };
+    return { outcome: "abandon", finalDecision: fallbackDecision, iterationsUsed: maxIterations, totalTurnsUsed, totalCostUsd, iterations };
+}
+/**
+ * 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 async function runIterateLoop(input, deps) {
+    const tracker = { totals: ZERO_METER_TOTALS, breaches: [] };
+    const core = await runIterateLoopCore(input, deps, tracker);
+    return { ...core, finalMeterTotals: tracker.totals, budgetBreaches: tracker.breaches };
+}

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

@@ -0,0 +1,98 @@
+import type { SelfReviewVerdict } from "./self-review-adapter.js";
+/** The three outcomes `decideNextAction` may reach. */
+export type IterateLoopAction = "continue" | "handoff" | "abandon";
+/** Every distinct reason `decideNextAction` can abandon for -- kept as a closed literal union so a caller
+ *  recording the decision (the attempt-log primitive, per #2333) has a stable, exhaustive vocabulary. */
+export type AbandonReason = "rejection_signaled" | "self_review_ambiguous" | "max_iterations_reached" | "cost_ceiling_reached" | "no_progress";
+/**
+ * The self-review outcome as the policy needs it -- narrower than the full {@link SelfReviewVerdict} (self-
+ * review-adapter.ts, #2334) so `IterationState` stays a minimal, cheap-to-construct synthetic fixture in
+ * tests. `"ambiguous"` is NOT something {@link deriveSelfReviewOutcome} ever produces from a successfully
+ * returned verdict (a real verdict object always has a definite conclusion) -- it is constructed directly by
+ * the caller's own error handling when the self-review call itself throws (e.g. a calculator inside it errors),
+ * per #2333's own "self-review itself errors" abandon trigger.
+ */
+export type SelfReviewOutcome = {
+    readonly kind: "pass";
+} | {
+    readonly kind: "fail";
+    readonly blockerCodes: readonly string[];
+} | {
+    readonly kind: "ambiguous";
+    readonly reason?: string | undefined;
+};
+/** Derive the policy-relevant {@link SelfReviewOutcome} from a real, successfully computed
+ *  {@link SelfReviewVerdict}. Only ever returns `"pass"` or `"fail"` -- see that variant's own doc comment for
+ *  why `"ambiguous"` is constructed elsewhere. */
+export declare function deriveSelfReviewOutcome(verdict: SelfReviewVerdict): SelfReviewOutcome;
+/**
+ * Everything `decideNextAction` needs for one iteration's decision. Deliberately minimal and synthetic-
+ * fixture-friendly -- no driver, no worktree, no IO.
+ */
+export type IterationState = {
+    /** 1-indexed count of iterations attempted so far, INCLUDING this one. */
+    iterationNumber: number;
+    /** Hard ceiling enforced INSIDE this policy (#2333's own deliverable: not left to an external caller to
+     *  remember to enforce). `iterationNumber >= maxIterations` abandons regardless of self-review outcome. */
+    maxIterations: number;
+    /** True when the loop's own cumulative cost ceiling (e.g. total driver turns spent across every iteration of
+     *  this attempt so far, not just this one) has been reached or exceeded -- the loop mechanics' (#2333) OWN
+     *  "max-cost ceiling enforced inside the loop" deliverable, alongside the iteration ceiling above. This
+     *  policy has no notion of what "cost" means; the caller computes the boolean from whatever cost signal it
+     *  tracks. Optional and defaults to not-reached, so `IterationState` fixtures that predate this field remain
+     *  valid. */
+    costCeilingReached?: boolean | undefined;
+    selfReview: SelfReviewOutcome;
+    /** The prior iteration's `fail` blocker codes, for the no-progress detector -- `null` when there is no prior
+     *  iteration to compare (the first iteration, or the prior iteration did not reach a `fail` outcome). */
+    previousBlockerCodes: readonly string[] | null;
+    /** True when the target repo (or this contributor's history with it) has signaled it does not want
+     *  automated/AI-authored contributions -- an explicit AI-usage-policy ban, or a prior submission from this
+     *  same miner was closed/rejected on this exact repo. The caller resolves this (e.g. via the AI-policy-map
+     *  signals or the rejection-state-machine primitive already shipped in `packages/gittensory-miner/lib/`) and
+     *  passes it in; this policy does not compute it itself. */
+    rejectionSignaled: boolean;
+};
+/** Forward-looking INTERFACE for Phase 4 (submission), not an implementation of it -- Phase 4 lands as a later,
+ *  separate issue. Gives it a stable target instead of reverse-engineering the shape from the loop's internals. */
+export type HandoffPacket = {
+    /** Absolute path to (or a branch ref identifying) the worktree holding the passing attempt's changes. */
+    worktreePath: string;
+    branchRef?: string | undefined;
+    /** Human-readable summary of the final diff, for the submission's own PR description. */
+    diffSummary: string;
+    /** The PASSING self-review verdict that authorized this handoff -- always has `passesPredictedGate: true`
+     *  (constructing a packet from anything else is a caller bug, not something this type can prevent statically,
+     *  since `decideNextAction` is the actual enforcement point). */
+    selfReviewVerdict: SelfReviewVerdict;
+    /** Reference into the attempt-log primitive (`packages/gittensory-engine/src/miner/attempt-log.ts`) for this
+     *  attempt's full decision trail. */
+    attemptLogReference: string;
+};
+export type IterateLoopDecision = {
+    action: IterateLoopAction;
+    /** Machine-stable, human-readable reason -- always populated, including for `"continue"` and `"handoff"`, so
+     *  every decision (not just abandons) has an auditable reason string for the attempt-log. */
+    reason: string;
+    /** Populated only when `action === "abandon"`. */
+    abandonReason?: AbandonReason | undefined;
+};
+/**
+ * Decide the next action for one iteration. Pure; identical inputs always yield the identical decision.
+ *
+ * Precedence (each check short-circuits the ones below it):
+ * 1. `rejectionSignaled` -- ALWAYS abandons, even over an otherwise-passing self-review (disengage silently).
+ * 2. `selfReview.kind === "ambiguous"` -- abandons; never optimistically continues or hands off on ambiguity.
+ * 3. `selfReview.kind === "pass"` -- the ONLY path to `"handoff"`.
+ * 4. `iterationNumber >= maxIterations` -- abandons at the hard ceiling regardless of whether the blocker set
+ *    was still changing (genuine incremental progress does not buy unlimited iterations).
+ * 5. `costCeilingReached` -- abandons at the hard cost ceiling, same rationale as the iteration ceiling above.
+ * 6. The current `fail` blocker set is identical to `previousBlockerCodes` -- abandons (no progress, stop
+ *    wasting turns).
+ * 7. Otherwise -- continue.
+ */
+export declare function decideNextActionWithReason(state: IterationState): IterateLoopDecision;
+/** The bare `decideNextAction(state) -> "continue" | "handoff" | "abandon"` signature this issue's deliverable
+ *  calls for. For the WHY behind a decision (the attempt-log needs a reason string, not just the action), use
+ *  {@link decideNextActionWithReason} -- this is a thin projection over the same logic. */
+export declare function decideNextAction(state: IterationState): IterateLoopAction;

package/dist/miner/iterate-policy.js

@@ -0,0 +1,98 @@
+// Iterate-loop stop/abandon/handoff policy (#2335): the explicit POLICY the orchestration loop's control flow
+// (#2333, sibling issue) consults each iteration to decide among exactly three outcomes. Deliberately split
+// from the loop MECHANICS (#2333) so the actual thresholds/rules are one small, individually-reviewable, pure
+// artifact -- `decideNextAction` needs no driver, no worktree, no IO to test.
+//
+// STRATEGIC CONSTRAINTS this policy encodes (gittensory-miner-autonomy-roadmap):
+//   - "never auto-submit (P4) before governor+caps (P5)" -- a mandatory clean predicted-gate PASS is the ONLY
+//     path to `"handoff"`; an ambiguous or errored self-review downgrades to abandon, never optimistically
+//     hands off.
+//   - "disengage SILENTLY on rejection" (the Matplotlib "MJ Rathbun" cautionary tale) -- a rejection signal
+//     wins over EVERYTHING else, including a self-review that would otherwise pass. Continuing to submit to a
+//     repo that has already shown it does not want automated contributions is the exact anti-pattern this
+//     guards against, regardless of how good any individual attempt looks.
+//   - "reward MERGED net-positive (never submission volume)" -- the no-progress detector and the iteration/cost
+//     ceilings exist so a stuck loop stops wasting turns (or spend) chasing a submission that was never going
+//     to land, rather than grinding toward *a* submission for its own sake.
+//
+// AUTONOMY DIAL (not yet wired): `src/settings/autonomy.ts`'s `resolveAutonomy`/`isActingAutonomyLevel` is the
+// existing reusable deny-by-default pattern this policy's eventual live autonomy-level check should consult
+// once `.gittensory-miner.yml` defines autonomy fields -- that wiring is explicitly left to a later phase; this
+// module's `decideNextAction` is autonomy-level-agnostic today.
+/** Derive the policy-relevant {@link SelfReviewOutcome} from a real, successfully computed
+ *  {@link SelfReviewVerdict}. Only ever returns `"pass"` or `"fail"` -- see that variant's own doc comment for
+ *  why `"ambiguous"` is constructed elsewhere. */
+export function deriveSelfReviewOutcome(verdict) {
+    if (verdict.passesPredictedGate)
+        return { kind: "pass" };
+    return { kind: "fail", blockerCodes: verdict.predictedGateVerdict.blockers.map((blocker) => blocker.code) };
+}
+function blockerSetsEqual(current, previous) {
+    if (current.length !== previous.length)
+        return false;
+    const currentSet = new Set(current);
+    const previousSet = new Set(previous);
+    if (currentSet.size !== previousSet.size)
+        return false;
+    for (const code of currentSet)
+        if (!previousSet.has(code))
+            return false;
+    return true;
+}
+/**
+ * Decide the next action for one iteration. Pure; identical inputs always yield the identical decision.
+ *
+ * Precedence (each check short-circuits the ones below it):
+ * 1. `rejectionSignaled` -- ALWAYS abandons, even over an otherwise-passing self-review (disengage silently).
+ * 2. `selfReview.kind === "ambiguous"` -- abandons; never optimistically continues or hands off on ambiguity.
+ * 3. `selfReview.kind === "pass"` -- the ONLY path to `"handoff"`.
+ * 4. `iterationNumber >= maxIterations` -- abandons at the hard ceiling regardless of whether the blocker set
+ *    was still changing (genuine incremental progress does not buy unlimited iterations).
+ * 5. `costCeilingReached` -- abandons at the hard cost ceiling, same rationale as the iteration ceiling above.
+ * 6. The current `fail` blocker set is identical to `previousBlockerCodes` -- abandons (no progress, stop
+ *    wasting turns).
+ * 7. Otherwise -- continue.
+ */
+export function decideNextActionWithReason(state) {
+    if (state.rejectionSignaled) {
+        return { action: "abandon", abandonReason: "rejection_signaled", reason: "Repo or contributor has signaled it does not want automated contributions; disengaging silently rather than retry-hammering." };
+    }
+    if (state.selfReview.kind === "ambiguous") {
+        return {
+            action: "abandon",
+            abandonReason: "self_review_ambiguous",
+            reason: `Self-review could not conclusively determine pass/fail${state.selfReview.reason ? `: ${state.selfReview.reason}` : "."} Downgrading to abandon rather than optimistically handing off.`,
+        };
+    }
+    if (state.selfReview.kind === "pass") {
+        return { action: "handoff", reason: "Self-review reached a clean predicted-gate pass." };
+    }
+    if (state.iterationNumber >= state.maxIterations) {
+        return {
+            action: "abandon",
+            abandonReason: "max_iterations_reached",
+            reason: `Reached the iteration ceiling (${state.maxIterations}) without a clean predicted-gate pass.`,
+        };
+    }
+    if (state.costCeilingReached === true) {
+        return {
+            action: "abandon",
+            abandonReason: "cost_ceiling_reached",
+            reason: "Reached the attempt's cost ceiling (cumulative driver spend across every iteration so far) without a clean predicted-gate pass.",
+        };
+    }
+    if (state.previousBlockerCodes !== null && blockerSetsEqual(state.selfReview.blockerCodes, state.previousBlockerCodes)) {
+        return {
+            action: "abandon",
+            abandonReason: "no_progress",
+            reason: `Blocker set unchanged from the prior iteration (${state.selfReview.blockerCodes.join(", ") || "no blockers listed"}); stopping rather than repeating an attempt that is not converging.`,
+        };
+    }
+    return { action: "continue", reason: "Self-review still failing but the blocker set changed since the prior iteration; continuing." };
+}
+/** The bare `decideNextAction(state) -> "continue" | "handoff" | "abandon"` signature this issue's deliverable
+ *  calls for. For the WHY behind a decision (the attempt-log needs a reason string, not just the action), use
+ *  {@link decideNextActionWithReason} -- this is a thin projection over the same logic. */
+export function decideNextAction(state) {
+    return decideNextActionWithReason(state).action;
+}

package/dist/miner/lint-guard.d.ts

@@ -0,0 +1,50 @@
+import type { CodingAgentDriverResult } from "./coding-agent-driver.js";
+/** Which existing check governs a changed file. `root` covers `src/**` and any non-`.js` file under
+ *  `packages/gittensory-miner`/`packages/gittensory-mcp` (e.g. a hand-written `.d.ts`), since those are
+ *  type-checked by the root `tsc --noEmit`, not `node --check`. */
+export type LintGuardPackage = "ui" | "engine" | "miner-js" | "mcp-js" | "root";
+/** Classify a changed file path (POSIX or Windows separators) into the package whose existing check governs
+ *  it. Pure path matching -- no filesystem access. */
+export declare function classifyLintGuardPackage(path: string): LintGuardPackage;
+/** Injected process runner -- real IO lives here, not in `guardChangedFiles`, so tests never spawn a real
+ *  subprocess. `ok` is derived from the exit code by the caller of this function, not by this type. */
+export type LintGuardSpawnFn = (cmd: string, args: readonly string[], opts: {
+    cwd: string;
+}) => Promise<{
+    code: number | null;
+    output: string;
+}>;
+export type LintGuardCheckResult = {
+    package: LintGuardPackage;
+    file: string;
+    command: string;
+    ok: boolean;
+    output: string;
+};
+/** Structured result -- never a thrown exception -- so a caller (the self-review loop, #2333) can
+ *  distinguish "the edit doesn't typecheck" (a `checks` entry with `ok: false`) from "the coding agent
+ *  itself failed" (a separate concern entirely, see {@link guardCodingAgentDriverResult}). */
+export type LintGuardResult = {
+    ok: boolean;
+    checks: readonly LintGuardCheckResult[];
+};
+export type LintGuardOptions = {
+    spawn: LintGuardSpawnFn;
+    /** Repo root the checks run from. Default: `process.cwd()`. */
+    cwd?: string | undefined;
+};
+/**
+ * Run the existing check for every package a changed file belongs to. One check per package group, not one
+ * per file (except `node --check`, which is inherently per-file) -- `tsc`/`ui:typecheck` validate a whole
+ * package at once, so re-running them per file would be redundant work, not extra coverage.
+ */
+export declare function guardChangedFiles(changedFiles: readonly string[], options: LintGuardOptions): Promise<LintGuardResult>;
+export type LintGuardedDriverResult = CodingAgentDriverResult & {
+    lintGuard: LintGuardResult;
+};
+/**
+ * Decorate a `CodingAgentDriver` result with its lint-guard verdict. Skips the guard entirely (an empty,
+ * passing `lintGuard`) when the driver itself failed or reported no changed files -- there is nothing to
+ * check, and running checks against an untouched tree would only produce a misleading unrelated result.
+ */
+export declare function guardCodingAgentDriverResult(result: CodingAgentDriverResult, options: LintGuardOptions): Promise<LintGuardedDriverResult>;

package/dist/miner/lint-guard.js

@@ -0,0 +1,68 @@
+const MINER_JS_EXTENSION = /\.(js|mjs|cjs)$/;
+/** Classify a changed file path (POSIX or Windows separators) into the package whose existing check governs
+ *  it. Pure path matching -- no filesystem access. */
+export function classifyLintGuardPackage(path) {
+    const normalized = path.replace(/\\/g, "/").replace(/^\.\//, "");
+    if (normalized.startsWith("apps/gittensory-ui/"))
+        return "ui";
+    if (normalized.startsWith("packages/gittensory-engine/"))
+        return "engine";
+    if (normalized.startsWith("packages/gittensory-miner/") && MINER_JS_EXTENSION.test(normalized))
+        return "miner-js";
+    if (normalized.startsWith("packages/gittensory-mcp/") && MINER_JS_EXTENSION.test(normalized))
+        return "mcp-js";
+    return "root";
+}
+const PACKAGE_COMMAND = Object.freeze({
+    root: Object.freeze(["npm", "run", "typecheck"]),
+    engine: Object.freeze(["npm", "run", "build", "--workspace", "@loopover/engine"]),
+    ui: Object.freeze(["npm", "run", "ui:typecheck"]),
+});
+async function runPackageCheck(pkg, files, spawn, cwd) {
+    if (pkg === "miner-js" || pkg === "mcp-js") {
+        // node --check is inherently per-file, unlike the whole-package tsc/ui:lint commands below.
+        const results = [];
+        for (const file of files) {
+            const { code, output } = await spawn("node", ["--check", file], { cwd });
+            results.push({ package: pkg, file, command: `node --check ${file}`, ok: code === 0, output });
+        }
+        return results;
+    }
+    const command = PACKAGE_COMMAND[pkg];
+    const { code, output } = await spawn(command[0], command.slice(1), { cwd });
+    return [{ package: pkg, file: files.join(", "), command: command.join(" "), ok: code === 0, output }];
+}
+/**
+ * Run the existing check for every package a changed file belongs to. One check per package group, not one
+ * per file (except `node --check`, which is inherently per-file) -- `tsc`/`ui:typecheck` validate a whole
+ * package at once, so re-running them per file would be redundant work, not extra coverage.
+ */
+export async function guardChangedFiles(changedFiles, options) {
+    const cwd = options.cwd ?? process.cwd();
+    const byPackage = new Map();
+    for (const file of changedFiles) {
+        const pkg = classifyLintGuardPackage(file);
+        const list = byPackage.get(pkg);
+        if (list)
+            list.push(file);
+        else
+            byPackage.set(pkg, [file]);
+    }
+    const checks = [];
+    for (const [pkg, files] of byPackage) {
+        checks.push(...(await runPackageCheck(pkg, files, options.spawn, cwd)));
+    }
+    return { ok: checks.every((check) => check.ok), checks };
+}
+/**
+ * Decorate a `CodingAgentDriver` result with its lint-guard verdict. Skips the guard entirely (an empty,
+ * passing `lintGuard`) when the driver itself failed or reported no changed files -- there is nothing to
+ * check, and running checks against an untouched tree would only produce a misleading unrelated result.
+ */
+export async function guardCodingAgentDriverResult(result, options) {
+    if (!result.ok || result.changedFiles.length === 0) {
+        return { ...result, lintGuard: { ok: true, checks: [] } };
+    }
+    const lintGuard = await guardChangedFiles(result.changedFiles, options);
+    return { ...result, ok: result.ok && lintGuard.ok, lintGuard };
+}