@alecsibilia/luca 14.0.0-alpha.2 → 14.0.0-alpha.21

package/engine/core/decide-final-fix.ts

@@ -0,0 +1,203 @@
+/**
+ * The final review's fix round (`fixStep`): the fixers, the gates and their
+ * fix loop, the fix commit, and the push, after the lenses found blocking
+ * findings. Pure.
+ */
+import { environmentFailedDetail } from './environment-rerun'
+import { failureCap } from './final-failure-cap'
+import {
+    stuck,
+    type DecideArgs,
+    type FinalReviewAction,
+} from './final-review-action'
+import {
+    finalFixerPrompt,
+    openFinalFindingsText,
+    type FinalFixerRole,
+} from './final-review-text'
+import {
+    CRASH_SECTION,
+    failedChecks,
+    failedTryMessage,
+    followUpSection,
+    gateFixMessage,
+} from './fix-loop-text'
+import { MAX_FIX_ROUNDS } from './loop-caps'
+import { badTestDetail, setupChangeDetail } from './stuck-text'
+
+import type { AgentRole } from '../agents/role-results'
+import { handoffRole, type ReplayedAgentFailure } from '../journal/replay'
+
+/**
+ * A fresh fixer of this role, told its findings (or the failed gates). With
+ * `follow_up`, it stands in for a follow-up whose session is gone, and its
+ * prompt carries the message. A fixer taking a turn a crash cut off is told
+ * of the crash.
+ */
+const launchFixer = ({
+    role,
+    review,
+    snapshot,
+    run_notes,
+    follow_up,
+}: DecideArgs & {
+    role: FinalFixerRole
+    follow_up?: string
+}): FinalReviewAction => {
+    const { fix } = review
+    if (fix === null) throw new Error('No final review fix round is open.')
+    // An implementer with no code findings left is here for failed gates.
+    const gates =
+        role === 'implementer' && fix.code_answered ? review.gates : null
+    const sections = [
+        ...(follow_up === undefined
+            ? []
+            : [followUpSection({ message: follow_up })]),
+        ...(review.crashed_turn === role ? [CRASH_SECTION] : []),
+    ]
+    return {
+        type: 'launch_final_fixer',
+        role,
+        prompt: finalFixerPrompt({
+            role,
+            snapshot,
+            fix,
+            gates,
+            run_notes,
+            sections,
+        }),
+        may_edit_tests: role === 'test-writer',
+    }
+}
+
+const isFixer = (role: AgentRole): role is FinalFixerRole =>
+    role === 'test-writer' || role === 'implementer'
+
+/**
+ * The next step after a fixer's failed turn: an engine failure starts a
+ * fresh fixer, any other a follow-up in its session (a fresh fixer with the
+ * same message with none), until its tries run out.
+ */
+const failedFixerStep = ({
+    failed,
+    ...args
+}: DecideArgs & { failed: ReplayedAgentFailure }): FinalReviewAction => {
+    const cap = failureCap({ review: args.review, failed })
+    if (cap !== null) return cap
+    const { role, error, failure, session_id } = failed
+    if (!isFixer(role)) throw new Error(`${role} is no final review fixer.`)
+    if (failure === 'engine') return launchFixer({ ...args, role })
+    const message = failedTryMessage({ failure, error })
+    if (session_id === null) {
+        return launchFixer({ ...args, role, follow_up: message })
+    }
+    return {
+        type: 'follow_up_final_fixer',
+        role,
+        session_id,
+        message,
+    }
+}
+
+/**
+ * A final review fix round, once every due lens finished and some finding
+ * blocks: start the round, a fresh test-writer for the test findings, then
+ * a fresh implementer for the code findings, then a fresh agent of the
+ * other writer role for findings a fixer answered `other_role` (#616), the
+ * gates (and their fix loop in the implementer's session, or a rerun when
+ * it answers `environment`, #613), the fix commit, and the push. `null` once
+ * the fixes are pushed.
+ */
+export const fixStep = (args: DecideArgs): FinalReviewAction | null => {
+    const { review, run_branch, snapshot } = args
+    const { fix } = review
+    if (fix === null) return null
+    // The fresh pass's one fix round runs past the cap (#548).
+    if (fix.round > MAX_FIX_ROUNDS && !review.fresh) {
+        return stuck({
+            reason: 'changes_requested',
+            detail: `The final review still asks for changes after ${MAX_FIX_ROUNDS} fix rounds:\n${openFinalFindingsText({ findings: fix.findings })}`,
+        })
+    }
+    if (!review.fixing_started) {
+        return { type: 'start_final_fix', round: fix.round }
+    }
+    const failed = [
+        review.agent_failures['test-writer'],
+        review.agent_failures.implementer,
+    ].find((entry) => entry !== undefined)
+    if (failed !== undefined) return failedFixerStep({ ...args, failed })
+    if (review.setup_change !== null) {
+        return stuck({
+            reason: 'setup_change_needed',
+            detail: setupChangeDetail({
+                ...review.setup_change,
+                setup_files: args.setup_files ?? [],
+            }),
+        })
+    }
+    if (!fix.tests_answered)
+        return launchFixer({ ...args, role: 'test-writer' })
+    if (!fix.code_answered) return launchFixer({ ...args, role: 'implementer' })
+    if (fix.bad_test !== null) {
+        return stuck({
+            reason: 'bad_test',
+            detail: `While fixing the final review's findings, the implementer sent a test back as bad: ${badTestDetail({ bad_test: fix.bad_test })}`,
+        })
+    }
+    const handoff = handoffRole({ fix })
+    if (handoff !== null) return launchFixer({ ...args, role: handoff })
+    const { gates } = review
+    const blamed = environmentFailedDetail({
+        environment: review.environment,
+        reruns: review.environment_reruns,
+        latest: gates,
+    })
+    if (blamed !== null) {
+        return stuck({ reason: 'environment_failed', detail: blamed })
+    }
+    if (gates === null) return { type: 'run_final_gates' }
+    if (!gates.ok) {
+        if (review.gate_fix_rounds >= MAX_FIX_ROUNDS) {
+            return stuck({
+                reason: 'gates_failed',
+                detail: `The gates still fail after the final review's fixes, after ${MAX_FIX_ROUNDS} fix rounds:\n${failedChecks({ gates })}`,
+            })
+        }
+        const session_id = review.sessions.implementer
+        const message = gateFixMessage({ gates })
+        if (session_id === undefined) {
+            return launchFixer({
+                ...args,
+                role: 'implementer',
+                follow_up: message,
+            })
+        }
+        return {
+            type: 'follow_up_final_fixer',
+            role: 'implementer',
+            session_id,
+            message,
+        }
+    }
+    if (review.commit === null) {
+        const hits = review.leftovers
+        if (hits !== null && hits.length > 0) {
+            return stuck({
+                reason: 'leftovers_found',
+                detail: hits
+                    .map(({ path, reason }) => `${path}: ${reason}`)
+                    .join('\n'),
+            })
+        }
+        return {
+            type: 'commit_final_fix',
+            round: fix.round,
+            message: `fix: final review round ${fix.round} for spec #${snapshot.spec.number}`,
+        }
+    }
+    if (review.pushed === null) {
+        return { type: 'push_final_fixes', branch: run_branch.branch }
+    }
+    return null
+}

package/engine/core/decide-final-review.ts

@@ -1,136 +1,22 @@
 import { crashDetail, crashedOut } from './decide-crashes'
+import { fixStep } from './decide-final-fix'
+import { failureCap } from './final-failure-cap'
 import {
-    finalFixerPrompt,
-    lensPrompt,
-    openFinalFindingsText,
-    type FinalFixerRole,
-} from './final-review-text'
-import {
-    CRASH_SECTION,
-    failedChecks,
-    failedTryMessage,
-    followUpSection,
-    gateFixMessage,
-} from './fix-loop-text'
-import { MAX_ENGINE_FAILURES, MAX_FIX_ROUNDS } from './loop-caps'
-
-import type { PromptRunNote } from '../agents/role-prompts'
-import {
-    LENS_NAMES,
-    lensRole,
-    type AgentRole,
-    type LensName,
-    type LensRole,
-} from '../agents/role-results'
-import type { StuckReason } from '../journal/journal-record'
-import {
-    isFinalKey,
-    type FinalReviewState,
-    type ReplayedAgentFailure,
-    type ReplayedGates,
-    type ReplayedSnapshot,
-    type ReplayedWorktree,
-} from '../journal/replay'
-import type { CrashCounts } from '../journal/step-records'
-
-/** The final review's steps, once every ticket pushed and before the PR. */
-export type FinalReviewAction =
-    /**
-     * Start a final review round: read the run branch's HEAD, the files
-     * since `from_sha`, and the config's rule files, then journal
-     * `final_review_started`.
-     */
-    | {
-          type: 'start_final_review'
-          round: number
-          from_sha: string
-          lenses: LensName[]
-      }
-    /** Start a fresh, read-only lens reviewer on the run branch. */
-    | { type: 'launch_lens'; lens: LensName; role: LensRole; prompt: string }
-    /** Every lens due this round approved. */
-    | { type: 'pass_final_review' }
-    /** A fix round on the lenses' findings starts. */
-    | { type: 'start_final_fix'; round: number }
-    /** Start a fresh fixer on the run branch's worktree. */
-    | {
-          type: 'launch_final_fixer'
-          role: FinalFixerRole
-          prompt: string
-          may_edit_tests: boolean
-      }
-    /** Send a follow-up to a fixer's open session (failed gates, a failed try). */
-    | {
-          type: 'follow_up_final_fixer'
-          role: FinalFixerRole
-          session_id: string
-          message: string
-      }
-    /** Run the engine config's gates on the run branch's worktree. */
-    | { type: 'run_final_gates' }
-    /** Scan for leftovers, then commit the fixes on the run branch. */
-    | { type: 'commit_final_fix'; round: number; message: string }
-    /** Push the run branch with the fixes to `origin`. */
-    | { type: 'push_final_fixes'; branch: string }
-    /** The engine can't safely pick the final review's next step by itself. */
-    | { type: 'mark_final_review_stuck'; reason: StuckReason; detail: string }
-
-const FINAL_REVIEW_ACTION_TYPES: ReadonlySet<string> = new Set<
-    FinalReviewAction['type']
->([
-    'start_final_review',
-    'launch_lens',
-    'pass_final_review',
-    'start_final_fix',
-    'launch_final_fixer',
-    'follow_up_final_fixer',
-    'run_final_gates',
-    'commit_final_fix',
-    'push_final_fixes',
-    'mark_final_review_stuck',
-])
-
-/**
- * Whether an action is one of the final review's.
- *
- * @example
- * isFinalReviewAction({ type: 'run_final_gates' }) // true
- */
-export const isFinalReviewAction = <Action extends { type: string }>(
-    action: Action
-): action is Extract<Action, FinalReviewAction> =>
-    FINAL_REVIEW_ACTION_TYPES.has(action.type)
+    stuck,
+    type DecideArgs,
+    type FinalReviewAction,
+    type FinalReviewDecision,
+} from './final-review-action'
+import { lensPrompt } from './final-review-text'
 
-/**
- * Where the final review stands for the build half of the decision step:
- * still working (these actions can run now), passed or shipped (open the
- * PR), or stuck (end the run until a reply).
- */
-export type FinalReviewDecision =
-    | { status: 'working'; actions: FinalReviewAction[] }
-    | { status: 'passed' }
-    | { status: 'shipped' }
-    | { status: 'stuck'; reason: StuckReason; detail: string }
+import { LENS_NAMES, lensRole, type LensName } from '../agents/role-results'
+import { isFinalKey } from '../journal/replay'
 
-type DecideArgs = {
-    review: FinalReviewState
-    /** Crashes in a row per scheduler key; the final review's are its own. */
-    crashes: CrashCounts
-    snapshot: ReplayedSnapshot
-    run_branch: ReplayedWorktree
-    /** The latest gates on the run branch. */
-    run_branch_gates: ReplayedGates | null
-    /** The run notes a fresh agent gets (`newestRunNotes`). */
-    run_notes: PromptRunNote[]
-}
-
-const stuck = ({
-    reason,
-    detail,
-}: {
-    reason: StuckReason
-    detail: string
-}): FinalReviewAction => ({ type: 'mark_final_review_stuck', reason, detail })
+export {
+    isFinalReviewAction,
+    type FinalReviewAction,
+    type FinalReviewDecision,
+} from './final-review-action'
 
 /** A fresh lens, or the step after its failed try. */
 const lensStep = ({
@@ -158,185 +44,6 @@ const lensStep = ({
     return failureCap({ review, failed }) ?? launch
 }
 
-/**
- * The stuck step when a failed turn used up its role's tries (or engine
- * failures in a row), else `null`: the role gets another go.
- */
-const failureCap = ({
-    review,
-    failed,
-}: {
-    review: FinalReviewState
-    failed: ReplayedAgentFailure
-}): FinalReviewAction | null => {
-    const { role, error, failure } = failed
-    if (failure === 'engine') {
-        const count = review.engine_failures[role] ?? 0
-        return count >= MAX_ENGINE_FAILURES
-            ? stuck({
-                  reason: 'agent_failed',
-                  detail: `The engine failed to run the ${role} ${count} times in a row: ${error}`,
-              })
-            : null
-    }
-    const tries = review.failed_tries[role] ?? 0
-    return tries >= MAX_FIX_ROUNDS
-        ? stuck({
-              reason: 'agent_failed',
-              detail: `The ${role} failed ${tries} tries in the final review; the last one: ${error}`,
-          })
-        : null
-}
-
-/**
- * A fresh fixer of this role, told its findings (or the failed gates). With
- * `follow_up`, it stands in for a follow-up whose session is gone, and its
- * prompt carries the message. A fixer taking a turn a crash cut off is told
- * of the crash.
- */
-const launchFixer = ({
-    role,
-    review,
-    snapshot,
-    run_notes,
-    follow_up,
-}: DecideArgs & {
-    role: FinalFixerRole
-    follow_up?: string
-}): FinalReviewAction => {
-    const { fix } = review
-    if (fix === null) throw new Error('No final review fix round is open.')
-    // An implementer with no code findings left is here for failed gates.
-    const gates =
-        role === 'implementer' && fix.code_answered ? review.gates : null
-    const sections = [
-        ...(follow_up === undefined
-            ? []
-            : [followUpSection({ message: follow_up })]),
-        ...(review.crashed_turn === role ? [CRASH_SECTION] : []),
-    ]
-    return {
-        type: 'launch_final_fixer',
-        role,
-        prompt: finalFixerPrompt({
-            role,
-            snapshot,
-            fix,
-            gates,
-            run_notes,
-            sections,
-        }),
-        may_edit_tests: role === 'test-writer',
-    }
-}
-
-const isFixer = (role: AgentRole): role is FinalFixerRole =>
-    role === 'test-writer' || role === 'implementer'
-
-/**
- * The next step after a fixer's failed turn: an engine failure starts a
- * fresh fixer, any other a follow-up in its session (a fresh fixer with the
- * same message with none), until its tries run out.
- */
-const failedFixerStep = ({
-    failed,
-    ...args
-}: DecideArgs & { failed: ReplayedAgentFailure }): FinalReviewAction => {
-    const cap = failureCap({ review: args.review, failed })
-    if (cap !== null) return cap
-    const { role, error, failure, session_id } = failed
-    if (!isFixer(role)) throw new Error(`${role} is no final review fixer.`)
-    if (failure === 'engine') return launchFixer({ ...args, role })
-    const message = failedTryMessage({ failure, error })
-    if (session_id === null) {
-        return launchFixer({ ...args, role, follow_up: message })
-    }
-    return {
-        type: 'follow_up_final_fixer',
-        role,
-        session_id,
-        message,
-    }
-}
-
-/**
- * A final review fix round, once every due lens finished and some finding
- * blocks: start the round, a fresh test-writer for the test findings, then
- * a fresh implementer for the code findings, the gates (and their fix loop
- * in the implementer's session), the fix commit, and the push. `null` once
- * the fixes are pushed.
- */
-const fixStep = (args: DecideArgs): FinalReviewAction | null => {
-    const { review, run_branch, snapshot } = args
-    const { fix } = review
-    if (fix === null) return null
-    if (fix.round > MAX_FIX_ROUNDS) {
-        return stuck({
-            reason: 'changes_requested',
-            detail: `The final review still asks for changes after ${MAX_FIX_ROUNDS} fix rounds:\n${openFinalFindingsText({ findings: fix.findings })}`,
-        })
-    }
-    if (!review.fixing_started) {
-        return { type: 'start_final_fix', round: fix.round }
-    }
-    const failed = [
-        review.agent_failures['test-writer'],
-        review.agent_failures.implementer,
-    ].find((entry) => entry !== undefined)
-    if (failed !== undefined) return failedFixerStep({ ...args, failed })
-    if (!fix.tests_answered)
-        return launchFixer({ ...args, role: 'test-writer' })
-    if (!fix.code_answered) return launchFixer({ ...args, role: 'implementer' })
-    if (fix.bad_test !== null) {
-        const { file, name, reason } = fix.bad_test
-        const where = [file, name].filter(Boolean).join(' > ')
-        return stuck({
-            reason: 'bad_test',
-            detail: `While fixing the final review's findings, the implementer sent a test back as bad: ${where === '' ? reason : `${where}: ${reason}`}`,
-        })
-    }
-    const { gates } = review
-    if (gates === null) return { type: 'run_final_gates' }
-    if (!gates.ok) {
-        if (review.gate_fix_rounds >= MAX_FIX_ROUNDS) {
-            return stuck({
-                reason: 'gates_failed',
-                detail: `The gates still fail after the final review's fixes, after ${MAX_FIX_ROUNDS} fix rounds:\n${failedChecks({ gates })}`,
-            })
-        }
-        const session_id = review.sessions.implementer
-        if (session_id === undefined) {
-            return launchFixer({ ...args, role: 'implementer' })
-        }
-        return {
-            type: 'follow_up_final_fixer',
-            role: 'implementer',
-            session_id,
-            message: gateFixMessage({ gates }),
-        }
-    }
-    if (review.commit === null) {
-        const hits = review.leftovers
-        if (hits !== null && hits.length > 0) {
-            return stuck({
-                reason: 'leftovers_found',
-                detail: hits
-                    .map(({ path, reason }) => `${path}: ${reason}`)
-                    .join('\n'),
-            })
-        }
-        return {
-            type: 'commit_final_fix',
-            round: fix.round,
-            message: `fix: final review round ${fix.round} for spec #${snapshot.spec.number}`,
-        }
-    }
-    if (review.pushed === null) {
-        return { type: 'push_final_fixes', branch: run_branch.branch }
-    }
-    return null
-}
-
 /**
  * The final review: the decision step's part between the last ticket's push
  * and the PR. Pure. It always runs, even for a one-ticket spec.
@@ -350,8 +57,18 @@ const fixStep = (args: DecideArgs): FinalReviewAction | null => {
  * the run branch, and a push. Then only the lenses that had blocking
  * findings re-review only the new changes (from the last round's HEAD),
  * with their earlier findings and the fixers' answers, and rule on each
- * "won't fix". A review still asking for changes after `MAX_FIX_ROUNDS` fix
+ * "won't fix". With a slow test command (#563), round 1 also runs the slow
+ * tests once every lens finished, and settles only once they ran; failing
+ * ones open the fix round (or join it). A fix round with no finding, opened only
+ * by them, is just its gates (which run the slow tests again) with their
+ * fix loop, the commit, and the push, with no lens re-review.
+ * A review still asking for changes after `MAX_FIX_ROUNDS` fix
  * rounds is stuck, and so is a failed fix loop, a bad test, or a leftover.
+ * Once a fix commit was pushed and no blocking finding is left, the fresh
+ * pass (#548) has all five lenses read the whole branch again, without
+ * earlier findings; its blocking findings get one fix round (past the round
+ * cap, too) and one re-review, and what is still open then tops the PR
+ * instead of getting the review stuck.
  * Failed tries are capped per role like a ticket's. A stuck final review
  * waits for a reply; `ship` opens the PR anyway. A final review step cut
  * off by a crash `MAX_CRASHES` times in a row is stuck too.
@@ -399,9 +116,37 @@ export const decideFinalReview = (args: DecideArgs): FinalReviewDecision => {
         )
         return working(stop === undefined ? steps : [stop])
     }
-    if (review.fix === null) return working([{ type: 'pass_final_review' }])
+    // Round 1's slow tests run once its lenses are in, never beside them:
+    // a lens's after-turn guard judges the run branch's worktree, so nothing
+    // else may write there while a lens runs. The round waits for them (#563).
+    if (review.slow_due && review.slow_tests === null) {
+        return working([{ type: 'run_final_slow_tests' }])
+    }
+    // Clean after a fix commit: every lens reads the whole branch once more,
+    // fresh, before the PR opens (#548). Once per final review; with no fix
+    // commit, round 1 was already a full fresh read.
+    const ending: FinalReviewAction =
+        review.fix_pushed && !review.fresh_started
+            ? {
+                  type: 'start_final_review',
+                  round: review.round + 1,
+                  from_sha: run_branch.base_sha,
+                  lenses: [...LENS_NAMES],
+                  fresh: true,
+              }
+            : { type: 'pass_final_review' }
+    if (review.fix === null) return working([ending])
+    // The fresh pass's fix was re-checked: what is still open tops the PR,
+    // and the final review never gets stuck on it (#548).
+    if (review.fresh_started && !review.fresh) {
+        return working([{ type: 'pass_final_review' }])
+    }
     const step = fixStep(args)
     if (step !== null) return working([step])
+    // A fix round opened only by failing slow tests ends at its push: its
+    // gates ran the slow tests on what was pushed, and no lens had a finding
+    // to look at again (#563), so the fresh pass comes next.
+    if (review.fix.findings.length === 0) return working([ending])
     // The fixes are pushed: the lenses with blocking findings look again.
     return working([
         {