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

package/engine/core/execute.ts

@@ -1,23 +1,27 @@
-import { basename, dirname } from 'node:path'
-
-import has from 'lodash/has'
-import partition from 'lodash/partition'
-
-import { decideSteps, type EngineAction } from './decide'
-import { isFinalReviewAction } from './decide-final-review'
-import { isMemoryAction } from './decide-memory'
-import type { PlanAction } from './decide-plan'
-import type { UsageLineAction } from './decide-usage-line'
-import { executeAlreadyDoneAction } from './execute-already-done'
+/**
+ * `runEngine`: the scheduler that runs the decision step's actions, tickets'
+ * steps at the same time. Re-exports the run's first records and
+ * `executeAction` from the modules that carry them out.
+ */
+import { decideNext, type EngineAction } from './decide'
+import { repoWaitUnchecked } from './decide-repo-wait'
+import { executeAction, type StepTry } from './execute-action'
+import type { BuildDeps } from './execute-build'
+import { readEarlierRuns, type GoingRunsReader } from './execute-repo-wait'
+import { executeWithJev } from './execute-with-jev'
+import { createLiveFile } from './live-file'
 import {
-    buildContext,
-    executeBuildAction,
-    type BuildDeps,
-} from './execute-build'
-import { writeChangeset } from './execute-changeset'
-import { executeFinalReviewAction } from './execute-final-review'
-import { executeMemoryAction } from './execute-memory'
-import { executeStuckAction } from './execute-stuck'
+    agentRoleOf,
+    crashesIn,
+    followUpSessionOf,
+    keyOf,
+    redosFirst,
+    SLOW_ACTIONS,
+    stepOf,
+    ticketOf,
+    usesRunBranch,
+    WAIT_ACTIONS,
+} from './schedule-rules'
 import {
     closeSessions,
     finishedSessions,
@@ -25,45 +29,24 @@ import {
 } from './session-close'
 
 import type { BoardSync } from '../board/board-sync'
-import type { EngineConfig } from '../config/engine-config'
-import { lucaVersion } from '../config/luca-version'
-import { outsideBlockerNumbers } from '../intake/intake-checks'
-import type { IntakeProblem } from '../intake/intake-schemas'
-import { jevAsksAfter, jevAsksBefore } from '../jev/jev-jobs'
-import { askJevInShadow, type JevShadow } from '../jev/jev-shadow'
+import { hearSlotWaits } from '../gates/slot-waits'
+import { shadowAsker, type JevShadow } from '../jev/jev-shadow'
 import type { Journal } from '../journal/journal'
 import type { JournalRecord } from '../journal/journal-record'
-import { replayRun } from '../journal/replay'
 import {
-    crashesAfter,
     resumeEntry,
     stepFirstSeq,
     type CrashCounts,
 } from '../journal/step-records'
-import {
-    LIMIT_WAIT_NAP_MS,
-    limitWaitComment,
-    SYSTEM_CLOCK,
-    waitUntil,
-    type EngineClock,
-} from '../limits/limit-wait'
-import {
-    DEFAULT_USAGE_LINES,
-    LINE_OF,
-    runReadings,
-    usageLineEndedComment,
-    usageLineWaitComment,
-    type UsageLineDeps,
-    type UsageLines,
-} from '../limits/usage-line'
+import type { EngineClock } from '../limits/limit-wait'
+import { runReadings, type UsageLineDeps } from '../limits/usage-line'
 import type { MemoryDeps } from '../memory/memory-client'
-import { postCommentOnce, type CommentStep } from '../tracker/post-comment-once'
-import {
-    NEEDS_INFO_LABEL,
-    READY_LABEL,
-    type Tracker,
-    type TrackerIssue,
-} from '../tracker/tracker'
+import type { Tracker } from '../tracker/tracker'
+
+export { executeAction, type StepTry } from './execute-action'
+export { refusalComment } from './execute-intake'
+export { recordConfigReload, recordResume, startRun } from './run-start'
+export { keyOf, stepOf } from './schedule-rules'
 
 /** How many actions `runEngine` takes before it gives up, as a safety net. */
 export const DEFAULT_MAX_STEPS = 1000
@@ -74,770 +57,9 @@ export const STOP_ACTIONS: ReadonlySet<EngineAction['type']> = new Set([
     'invalid_journal',
 ])
 
-/**
- * Starts a run by writing its first record. The spec and config it names are
- * what every later step of the run works from; the Luca version it names is
- * the one the run started on.
- */
-export const startRun = ({
-    journal,
-    spec_number,
-    config,
-    base_branch,
-    memory,
-    repo,
-    luca_version = lucaVersion(),
-}: {
-    journal: Journal
-    spec_number: number
-    config: EngineConfig
-    /** The branch the run branch starts from. Defaults to `main`. */
-    base_branch?: string
-    /**
-     * Turns memory on (#370), with the project's vault (`null` searches only
-     * `default`). Leave it out for a run without memory.
-     */
-    memory?: { project_vault: string | null }
-    /** The repo the run is on, so a resume can find it. Defaults to `null`. */
-    repo?: string | null
-    /** Luca's version. Defaults to the engine's own. */
-    luca_version?: string
-}): JournalRecord =>
-    journal.append({
-        kind: 'run_started',
-        ticket: null,
-        role: null,
-        content: {
-            spec_number,
-            config,
-            base_branch,
-            memory: memory ?? null,
-            repo,
-            luca_version,
-        },
-    })
-
-/**
- * Records that the engine started again on a run's journal, on Luca's
- * version `luca_version`, before its first step.
- */
-export const recordResume = ({
-    journal,
-    luca_version = lucaVersion(),
-}: {
-    journal: Journal
-    /** Luca's version. Defaults to the engine's own. */
-    luca_version?: string
-}): JournalRecord =>
-    journal.append({
-        kind: 'engine_resumed',
-        ticket: null,
-        role: null,
-        content: { luca_version },
-    })
-
-/** The comment a bad spec or ticket gets when intake refuses the run. */
-export const refusalComment = ({
-    spec_number,
-    missing,
-}: {
-    spec_number: number
-    missing: string[]
-}): string =>
-    `Luca intake refused the run for spec #${spec_number}. This issue is not ready yet:\n\n` +
-    `${missing.map((line) => `- ${line}`).join('\n')}\n\n` +
-    `Fix these, move the issue back to \`${READY_LABEL}\`, and start the run again.`
-
-const readIntake = async ({
-    spec_number,
-    journal,
-    tracker,
-}: {
-    spec_number: number
-    journal: Journal
-    tracker: Tracker
-}) => {
-    const spec = await tracker.readSpec({ spec_number })
-    const subTickets = await tracker.listSubTickets({ spec_number })
-    const outside = await Promise.all(
-        outsideBlockerNumbers({ sub_tickets: subTickets }).map((number) =>
-            tracker.readIssue({ number })
-        )
-    )
-    journal.append({
-        kind: 'intake_read',
-        ticket: null,
-        role: null,
-        content: {
-            spec,
-            sub_tickets: subTickets,
-            outside_blockers: outside.filter(
-                (issue): issue is TrackerIssue => issue !== null
-            ),
-        },
-    })
-}
-
-const refuseIntake = async ({
-    spec_number,
-    problems,
-    journal,
-    tracker,
-    step,
-}: {
-    spec_number: number
-    problems: IntakeProblem[]
-    journal: Journal
-    tracker: Tracker
-    step: CommentStep
-}) => {
-    for (const [n, { ticket, missing }] of problems.entries()) {
-        if (ticket === null) continue
-        await postCommentOnce({
-            tracker,
-            number: ticket,
-            body: refusalComment({ spec_number, missing }),
-            step,
-            n,
-        })
-        await tracker.addLabel({ number: ticket, label: NEEDS_INFO_LABEL })
-        await tracker.removeLabel({ number: ticket, label: READY_LABEL })
-    }
-    journal.append({
-        kind: 'intake_refused',
-        ticket: null,
-        role: null,
-        content: { problems },
-    })
-}
-
-/**
- * Carries out a limit wait or a billing stop. A limit wait's start tells the
- * spec issue (unless it already heard of this reset) before it is journaled;
- * the wait itself sleeps by `clock` until its end, so a restarted engine
- * waits out only what is left.
- */
-const executePlanAction = async ({
-    action,
-    journal,
-    tracker,
-    clock,
-    step,
-}: {
-    action: Exclude<PlanAction, { type: 'done' }>
-    journal: Journal
-    tracker: Tracker
-    clock: EngineClock
-    step: CommentStep
-}): Promise<void> => {
-    switch (action.type) {
-        case 'start_limit_wait': {
-            const { rate_limit_type, resets_at, until, ticket, role } = action
-            if (action.announce) {
-                await postCommentOnce({
-                    tracker,
-                    number: action.spec_number,
-                    body: limitWaitComment({
-                        rate_limit_type,
-                        resets_at,
-                        until,
-                    }),
-                    step,
-                    n: 0,
-                })
-            }
-            journal.append({
-                kind: 'limit_wait_started',
-                ticket: null,
-                role: null,
-                content: {
-                    resets_at,
-                    until,
-                    rate_limit_type,
-                    hit_ticket: ticket,
-                    hit_role: role,
-                },
-            })
-            return
-        }
-        case 'wait_for_limit':
-            await waitUntil({ clock, until: action.until })
-            journal.append({
-                kind: 'limit_wait_ended',
-                ticket: null,
-                role: null,
-                content: { until: action.until },
-            })
-            return
-        case 'stop_for_billing':
-            journal.append({
-                kind: 'run_stopped',
-                ticket: null,
-                role: null,
-                content: { reason: action.reason, role: null, billing: true },
-            })
-            return
-    }
-}
-
-/**
- * Carries out a usage-line wait. Its start tells the spec issue, then is
- * journaled. The wait sleeps by `clock` in naps until its end, re-reading
- * the lines before each nap: a line raised above the reading ends it at
- * once. Its end tells the spec issue why the run carries on, then is
- * journaled.
- */
-const executeUsageLineAction = async ({
-    action,
-    journal,
-    tracker,
-    clock,
-    read_usage_lines,
-    step,
-}: {
-    action: UsageLineAction
-    journal: Journal
-    tracker: Tracker
-    clock: EngineClock
-    read_usage_lines: () => Promise<UsageLines>
-    step: CommentStep
-}): Promise<void> => {
-    const { spec_number, window, line, percent, until } = action
-    if (action.type === 'start_usage_line_wait') {
-        const { resets_at } = action
-        await postCommentOnce({
-            tracker,
-            number: spec_number,
-            body: usageLineWaitComment({ window, line, percent, resets_at }),
-            step,
-            n: 0,
-        })
-        journal.append({
-            kind: 'usage_line_wait_started',
-            ticket: null,
-            role: null,
-            content: { window, line, percent, resets_at, until },
-        })
-        return
-    }
-    const end = Date.parse(until)
-    let reason: 'reset' | 'line_raised' = 'reset'
-    for (;;) {
-        const lines = await read_usage_lines()
-        if (lines[LINE_OF[window]] > percent) {
-            reason = 'line_raised'
-            break
-        }
-        const left = end - clock.now()
-        if (left <= 0) break
-        await clock.sleep(Math.min(left, LIMIT_WAIT_NAP_MS))
-    }
-    await postCommentOnce({
-        tracker,
-        number: spec_number,
-        body: usageLineEndedComment({ window, percent, reason }),
-        step,
-        n: 0,
-    })
-    journal.append({
-        kind: 'usage_line_wait_ended',
-        ticket: null,
-        role: null,
-        content: { until, reason },
-    })
-}
-
-/**
- * Which try of its step an action is: the seq of the step's first try (its
- * first `step_started`), and whether this try redoes one a crash cut off.
- * A redo adopts the side effects its first try left behind: its comments,
- * its PR, its worktrees and commits.
- */
-export type StepTry = { first_seq: number; redo: boolean }
-
-/**
- * Carries out one action: talks to the tracker, then records what happened in
- * the journal. The only impure half of the engine; `decide` picks the action.
- *
- * Stop actions (`done`, `invalid_journal`) do nothing here.
- */
-export const executeAction = async ({
-    action,
-    journal,
-    tracker,
-    build,
-    clock,
-    reply_poll_ms,
-    memory,
-    step,
-    read_usage_lines,
-}: {
-    action: EngineAction
-    journal: Journal
-    tracker: Tracker
-    /** Needed for every step after intake. */
-    build?: BuildDeps
-    /** Limit waits and reply waits sleep by it. Defaults to `SYSTEM_CLOCK`. */
-    clock?: EngineClock
-    /** How long a reply wait sleeps before it reads the spec issue. */
-    reply_poll_ms?: number
-    /** The memory client, for a run with memory on (#370). */
-    memory?: MemoryDeps
-    /**
-     * Which try of its step this is, from the scheduler. Left out, it is a
-     * first try, numbered after the journal's last record.
-     */
-    step?: StepTry
-    /**
-     * Reads the `luca-board` usage lines, again before each nap of a
-     * usage-line wait. Left out, the lines never change during a wait.
-     */
-    read_usage_lines?: () => Promise<UsageLines>
-}): Promise<void> => {
-    const tried: CommentStep = {
-        run_id: basename(dirname(journal.file)),
-        ...(step ?? {
-            first_seq: (journal.read().at(-1)?.seq ?? 0) + 1,
-            redo: false,
-        }),
-    }
-    if (isMemoryAction(action)) {
-        return executeMemoryAction({
-            action,
-            journal,
-            tracker,
-            memory,
-            build,
-            step: tried,
-        })
-    }
-    switch (action.type) {
-        case 'report_stuck':
-        case 'wait_for_reply':
-        case 'take_reply':
-        case 'ignore_reply':
-        case 'skip_ticket':
-        case 'report_final_review_stuck':
-        case 'ship_final_review':
-        case 'retry_final_review':
-        case 'mark_run_stuck':
-        case 'report_run_stuck':
-            return executeStuckAction({
-                action,
-                journal,
-                tracker,
-                clock: clock ?? SYSTEM_CLOCK,
-                reply_poll_ms,
-                step: tried,
-            })
-        case 'stop_for_crashes':
-            journal.append({
-                kind: 'run_stopped',
-                ticket: null,
-                role: null,
-                content: {
-                    reason: action.reason,
-                    role: null,
-                    billing: false,
-                    crashed: true,
-                },
-            })
-            return
-        case 'record_usage':
-            journal.append({
-                kind: 'usage_recorded',
-                ticket: action.usage.ticket,
-                role: null,
-                content: action.usage,
-            })
-            return
-        case 'start_limit_wait':
-        case 'wait_for_limit':
-        case 'stop_for_billing':
-            return executePlanAction({
-                action,
-                journal,
-                tracker,
-                clock: clock ?? SYSTEM_CLOCK,
-                step: tried,
-            })
-        case 'start_usage_line_wait':
-        case 'wait_for_usage_line':
-            return executeUsageLineAction({
-                action,
-                journal,
-                tracker,
-                clock: clock ?? SYSTEM_CLOCK,
-                read_usage_lines:
-                    read_usage_lines ??
-                    (async () => ({
-                        ...DEFAULT_USAGE_LINES,
-                        [LINE_OF[action.window]]: action.line,
-                    })),
-                step: tried,
-            })
-        case 'read_intake':
-            return readIntake({
-                spec_number: action.spec_number,
-                journal,
-                tracker,
-            })
-        case 'refuse_intake':
-            return refuseIntake({
-                spec_number: action.spec_number,
-                problems: action.problems,
-                journal,
-                tracker,
-                step: tried,
-            })
-        case 'mark_already_done':
-        case 'close_ticket':
-            return executeAlreadyDoneAction({
-                action,
-                journal,
-                tracker,
-                step: tried,
-            })
-        case 'finish_nothing_to_do':
-            journal.append({
-                kind: 'nothing_to_do',
-                ticket: null,
-                role: null,
-                content: {
-                    closed_tickets: action.closed_tickets,
-                    already_done: action.already_done,
-                },
-            })
-            return
-        case 'snapshot_intake': {
-            const { spec, tickets, closed_tickets } = action.snapshot
-            journal.append({
-                kind: 'spec_snapshot',
-                ticket: spec.number,
-                role: null,
-                content: {
-                    spec,
-                    ticket_order: tickets.map((ticket) => ticket.number),
-                    closed_tickets,
-                },
-            })
-            for (const ticket of tickets) {
-                journal.append({
-                    kind: 'ticket_snapshot',
-                    ticket: ticket.number,
-                    role: null,
-                    content: ticket,
-                })
-            }
-            return
-        }
-        case 'invalid_journal':
-        case 'done':
-            return
-        default:
-            if (build === undefined) {
-                throw new Error(
-                    `The engine needs a git adapter and an agent launcher to ${action.type}.`
-                )
-            }
-            if (isFinalReviewAction(action)) {
-                return executeFinalReviewAction({
-                    action,
-                    context: buildContext({
-                        journal,
-                        tracker,
-                        step: tried,
-                        ...build,
-                    }),
-                })
-            }
-            if (action.type === 'write_changeset') {
-                return writeChangeset({
-                    action,
-                    context: buildContext({
-                        journal,
-                        tracker,
-                        step: tried,
-                        ...build,
-                    }),
-                })
-            }
-            return executeBuildAction({
-                action,
-                journal,
-                tracker,
-                step: tried,
-                ...build,
-            })
-    }
-}
-
-/**
- * The ticket an action works on, or `null` for a run-level action. The
- * plan's actions are the whole run's, whichever ticket hit the limit; a
- * ticket's usage record is that ticket's. Reading and taking replies is
- * the run's too (see `keyOf`).
- */
-const ticketOf = (action: EngineAction): number | null => {
-    switch (action.type) {
-        case 'start_limit_wait':
-        case 'wait_for_limit':
-        case 'stop_for_billing':
-        case 'wait_for_reply':
-        case 'take_reply':
-        case 'ignore_reply':
-            return null
-        case 'record_usage':
-            return action.usage.ticket
-        default:
-            return 'ticket' in action && typeof action.ticket === 'number'
-                ? action.ticket
-                : null
-    }
-}
-
-/**
- * Replies are read and taken beside the other steps, one at a time, under
- * their own key: waiting for a reply never holds a ticket up.
- */
-const REPLY_ACTIONS: ReadonlySet<EngineAction['type']> = new Set([
-    'wait_for_reply',
-    'take_reply',
-    'ignore_reply',
-])
-
-/**
- * The scheduler's key for an action: at most one action per key runs at a
- * time. Reading and taking replies has its own (`replies`). Each lens has
- * its own (`lens:<lens>`), so the five lenses review at once; the final review's other steps share `final`; a ticket's steps its
- * number; and the run's own steps `run`, which only ever run alone.
- */
-export const keyOf = (action: EngineAction): string => {
-    if (REPLY_ACTIONS.has(action.type)) return 'replies'
-    // A search waits under the key of the step it comes before: its
-    // ticket's, the final review's, or (the run's start) the run's.
-    if (action.type === 'recall_memories') {
-        if (action.ticket !== null) return String(action.ticket)
-        return action.point === 'run_start' ? 'run' : 'final'
-    }
-    if (action.type === 'launch_lens') return `lens:${action.lens}`
-    if (isFinalReviewAction(action)) return 'final'
-    const ticket = ticketOf(action)
-    return ticket === null ? 'run' : String(ticket)
-}
-
-/** Actions that are an agent's turn: their step names the role. */
-const AGENT_ACTIONS: ReadonlySet<EngineAction['type']> = new Set([
-    'launch_agent',
-    'follow_up_agent',
-    'launch_lens',
-    'launch_final_fixer',
-    'follow_up_final_fixer',
-])
-
-/** The agent role of an agent's turn (the learner's is `learner`), else `null`. */
-const agentRoleOf = (action: EngineAction): string | null => {
-    if (action.type === 'launch_learner') return 'learner'
-    return AGENT_ACTIONS.has(action.type) &&
-        'role' in action &&
-        action.role !== null
-        ? action.role
-        : null
-}
-
-/**
- * A step's name in the journal: its action type, plus `:<role>` for an
- * agent's turn, such as `follow_up_agent:implementer`.
- *
- * @example
- * stepOf({ type: 'run_gates', ticket: 11, target: 'ticket' }) // 'run_gates'
- */
-export const stepOf = (action: EngineAction): string => {
-    const role = agentRoleOf(action)
-    return role === null ? action.type : `${action.type}:${role}`
-}
-
-/**
- * Waits get no step records: a crash during one is no step's fault, and a
- * restarted engine just waits again (a limit wait until the same time).
- */
-const WAIT_ACTIONS: ReadonlySet<EngineAction['type']> = new Set([
-    'wait_for_reply',
-    'wait_for_limit',
-    'wait_for_usage_line',
-])
-
-/**
- * Steps that can run for minutes: installs, test runs, and agents' turns.
- * The board hears of them as they start, so a run never looks frozen.
- */
-const SLOW_ACTIONS: ReadonlySet<EngineAction['type']> = new Set([
-    ...AGENT_ACTIONS,
-    'launch_learner',
-    'install_dependencies',
-    'run_baseline_tests',
-    'run_red_check',
-    'run_gates',
-    'run_final_gates',
-])
-
-/**
- * Actions that read or move the run branch. At most one runs at a time, so
- * joins, their gates, pushes, and new worktrees see one run branch. The
- * final review's fixers, gates, commit, and push work in the run branch's
- * worktree; its lenses only read it.
- */
-const usesRunBranch = (action: EngineAction): boolean => {
-    switch (action.type) {
-        case 'create_ticket_worktree':
-        case 'join_run_branch':
-        case 'push_run_branch':
-        case 'rebase_ticket':
-        case 'start_final_review':
-        case 'launch_final_fixer':
-        case 'follow_up_final_fixer':
-        case 'run_final_gates':
-        case 'commit_final_fix':
-        case 'push_final_fixes':
-        case 'write_changeset':
-        case 'undo_join':
-        case 'retry_ticket':
-            return true
-        case 'run_gates':
-        case 'install_dependencies':
-            return action.target === 'run_branch'
-        // It puts back a run branch a join crashes cut off too often left.
-        case 'mark_stuck':
-            return action.reason === 'crashed'
-        default:
-            return false
-    }
-}
-
-/**
- * Carries out one action with Jev in shadow mode: asks Jev before it (ticket
- * order, model, skills), then after it about the records it appended
- * (failure kinds, finding severities). Only the action's own ticket's new
- * records count, since other tickets append at the same time. Jev's answers
- * change nothing.
- */
-const executeWithJev = async ({
-    jev,
-    action,
-    journal,
-    tracker,
-    build,
-    clock,
-    reply_poll_ms,
-    memory,
-    step,
-    read_usage_lines,
-}: {
-    jev: JevShadow
-    action: EngineAction
-    journal: Journal
-    tracker: Tracker
-    build?: BuildDeps
-    clock?: EngineClock
-    reply_poll_ms?: number
-    memory?: MemoryDeps
-    step?: StepTry
-    read_usage_lines?: () => Promise<UsageLines>
-}): Promise<void> => {
-    const shadow = { jev: jev.client, journal, timeout_ms: jev.timeout_ms }
-    await askJevInShadow({
-        ...shadow,
-        asks: jevAsksBefore({
-            action,
-            state: replayRun({ records: journal.read() }),
-        }),
-    })
-    const lastSeq = journal.read().at(-1)?.seq ?? 0
-    await executeAction({
-        action,
-        journal,
-        tracker,
-        build,
-        clock,
-        reply_poll_ms,
-        memory,
-        step,
-        read_usage_lines,
-    })
-    const records = journal.read()
-    await askJevInShadow({
-        ...shadow,
-        asks: jevAsksAfter({
-            records: records.filter(
-                (record) =>
-                    record.seq > lastSeq && ownsRecord({ action, record })
-            ),
-            state: replayRun({ records }),
-        }),
-    })
-}
-
-/**
- * Whether a record appended while `action` ran is that action's own, since
- * other tickets (or other lenses) append at the same time: a ticket's
- * records for a ticket's step, a lens's for its lens, and the final
- * review's other ticket-less records for its other steps.
- */
-const ownsRecord = ({
-    action,
-    record,
-}: {
-    action: EngineAction
-    record: JournalRecord
-}): boolean => {
-    if (action.type === 'launch_lens') {
-        return (
-            record.ticket === null &&
-            (record.role === null || record.role === action.role)
-        )
-    }
-    if (isFinalReviewAction(action)) {
-        return record.ticket === null && !record.role?.endsWith('-lens')
-    }
-    const ticket = ticketOf(action)
-    return ticket === null || record.ticket === ticket
-}
-
-/** The crash counts per key, from the journal's records. */
-const crashesIn = (records: JournalRecord[]): CrashCounts =>
-    records.reduce<CrashCounts>(
-        (crashes, record) => crashesAfter({ crashes, record }),
-        {}
-    )
-
-/**
- * The actions on keys a crash cut a step off first, in their order, then
- * the rest: a step a crash cut off (or the stop for it) starts before any
- * other, so a half-done change to the run branch, such as a join, is put
- * right before another step reads the run branch.
- */
-const redosFirst = ({
-    actions,
-    crashes,
-}: {
-    actions: EngineAction[]
-    crashes: CrashCounts
-}): EngineAction[] => {
-    const [redos, rest] = partition(actions, (action) =>
-        has(crashes, keyOf(action))
-    )
-    return [...redos, ...rest]
-}
-
 /** One action the engine started and has not seen settle yet. */
 type InFlight = { action: EngineAction; done: Promise<void> }
 
-/** The session a follow-up goes to, if the action is one. */
-const followUpSessionOf = (action: EngineAction): string[] =>
-    action.type === 'follow_up_agent' || action.type === 'follow_up_final_fixer'
-        ? [action.session_id]
-        : []
-
 /**
  * Runs the engine: a scheduler over the decision step. Each pass it decides
  * every action that can run now from the journal and starts those it can,
@@ -862,8 +84,10 @@ const followUpSessionOf = (action: EngineAction): string[] =>
  * let finish, then the first error is thrown. `max_steps` counts the actions
  * started.
  *
- * With `jev`, Jev is asked around each step in **shadow mode** and its
- * answers are journaled but never acted on. Without it, nothing changes.
+ * With `jev`, the decision model is asked around each step in **shadow
+ * mode** and its answers are journaled but never acted on (see
+ * `shadowAsker`; a rejected token turns it off for the rest of this call).
+ * Without it, nothing changes.
  *
  * With `memory`, a run whose `run_started` turned memory on searches
  * MuninnDB at each recall point and saves the learner's memories at its
@@ -873,6 +97,11 @@ const followUpSessionOf = (action: EngineAction): string[] =>
  * With `board`, the whole journal is sent to the board once before the
  * first step and again after each step settles.
  *
+ * A ticket held on purpose between steps (another ticket's shared
+ * baseline, the join queue, the start queue) gets one `ticket_waiting` as
+ * its wait starts, from the same decision as the steps (`decideNext`),
+ * sent to the board at once.
+ *
  * A rejected plan limit is a limit wait: the engine sleeps by `clock` until
  * the window resets, then carries on. Overage or a billing error ends the
  * run for good (`done`, outcome `stopped`).
@@ -881,6 +110,16 @@ const followUpSessionOf = (action: EngineAction): string[] =>
  * decision it shares its readings with every run, reads the newest shared
  * ones and the lines, and pauses at a line (see `decide-usage-line.ts`).
  *
+ * With `going_runs`, a run started while an earlier run on the same repo
+ * is going waits for it before intake: a **repo wait** (see
+ * `decide-repo-wait.ts`).
+ *
+ * With `live_file`, the engine keeps the run's live file there while it
+ * runs (`live-file.ts`, #628): what each agent in a turn is doing now,
+ * never journaled, and each ticket check's wait for a prepare slot or a
+ * test slot while it lasts (#632). It is written a last time, with no
+ * agents, at the end.
+ *
  * Crash recovery: every step it starts (not a wait) is journaled between a
  * `step_started` and a `step_ended` (none when the step throws). On start,
  * a step with no `step_ended` was cut off by a crash: one `run_resumed`
@@ -909,6 +148,8 @@ export const runEngine = async ({
     reply_poll_ms,
     memory,
     usage,
+    going_runs,
+    live_file,
 }: Partial<BuildDeps> & {
     journal: Journal
     tracker: Tracker
@@ -916,7 +157,7 @@ export const runEngine = async ({
     max_steps?: number
     /** Action types to stop at without carrying them out, such as in tests. */
     stop_before?: EngineAction['type'][]
-    /** Jev in shadow mode. Leave it out to run without Jev. */
+    /** The decision model in shadow mode. Leave it out to run without one. */
     jev?: JevShadow
     /** Sends the journal to the board after every step. Never throws. */
     board?: BoardSync
@@ -931,18 +172,32 @@ export const runEngine = async ({
     memory?: MemoryDeps
     /** The usage lines and the shared readings. Left out, there is no usage line. */
     usage?: UsageLineDeps
+    /**
+     * Lists the unfinished runs (`goingRuns`), for the repo wait before
+     * intake. Left out, there is no repo wait.
+     */
+    going_runs?: GoingRunsReader
+    /**
+     * Where to keep the run's live file (#628), such as
+     * `runLiveFilePath({ runs_dir, run_id })`. Left out, there is none.
+     */
+    live_file?: string
 }): Promise<EngineAction> => {
     const limit = max_steps ?? DEFAULT_MAX_STEPS
     const stops = new Set([...STOP_ACTIONS, ...(stop_before ?? [])])
+    const live =
+        live_file === undefined ? null : createLiveFile({ file: live_file })
     const build =
         git === undefined || launcher === undefined
             ? undefined
-            : { git, launcher }
+            : { git, launcher: live?.launcher(launcher) ?? launcher }
     const inFlight = new Map<string, InFlight>()
     let started = 0
+    // The run's own asker, so turning the decision model off lasts this run.
+    const ask = jev === undefined ? undefined : shadowAsker({ jev, journal })
 
     const execute = (action: EngineAction, step?: StepTry): Promise<void> =>
-        jev === undefined
+        ask === undefined
             ? executeAction({
                   action,
                   journal,
@@ -953,9 +208,10 @@ export const runEngine = async ({
                   memory,
                   step,
                   read_usage_lines: usage?.read_lines,
+                  going_runs,
               })
             : executeWithJev({
-                  jev,
+                  ask,
                   action,
                   journal,
                   tracker,
@@ -965,18 +221,27 @@ export const runEngine = async ({
                   memory,
                   step,
                   read_usage_lines: usage?.read_lines,
+                  going_runs,
               })
 
-    /** The decision step, with the usage line when the run has one. */
+    /**
+     * The decision step, with the usage line when the run has one, and the
+     * earlier runs on the repo while the run has yet to look for them.
+     */
     const decideNow = async (
         records: JournalRecord[]
-    ): Promise<EngineAction[]> => {
-        if (usage === undefined) return decideSteps({ records })
+    ): Promise<ReturnType<typeof decideNext>> => {
+        const earlier_runs =
+            going_runs !== undefined && repoWaitUnchecked({ records })
+                ? (await readEarlierRuns({ going_runs, journal })).runs
+                : undefined
+        if (usage === undefined) return decideNext({ records, earlier_runs })
         await usage.share(runReadings({ records }))
-        return decideSteps({
+        return decideNext({
             records,
             usage_lines: await usage.read_lines(),
             shared_readings: await usage.read_shared(),
+            earlier_runs,
         })
     }
     const settleAll = () =>
@@ -1014,10 +279,18 @@ export const runEngine = async ({
             ...who,
             content: { key, step, first_seq },
         })
-        await execute(action, {
-            first_seq: first_seq ?? started.seq,
-            redo: first_seq !== null,
-        })
+        const run = () =>
+            execute(action, {
+                first_seq: first_seq ?? started.seq,
+                redo: first_seq !== null,
+            })
+        // A ticket's check waiting for a slot shows in the live file (#632).
+        await (live === null || who.ticket === null
+            ? run()
+            : hearSlotWaits({
+                  listener: live.slotWaits({ ticket: who.ticket }),
+                  run,
+              }))
         journal.append({ kind: 'step_ended', ...who, content: { key, step } })
     }
 
@@ -1048,10 +321,8 @@ export const runEngine = async ({
             await closeFinished({ all: false })
             const records = journal.read()
             const crashes = crashesIn(records)
-            const actions = redosFirst({
-                actions: await decideNow(records),
-                crashes,
-            })
+            const decided = await decideNow(records)
+            const actions = redosFirst({ actions: decided.actions, crashes })
             const stop = actions.find((action) => stops.has(action.type))
             if (stop !== undefined && inFlight.size === 0) {
                 if (STOP_ACTIONS.has(stop.type)) {
@@ -1060,7 +331,24 @@ export const runEngine = async ({
                 return stop
             }
             let slowStarted = false
+            let waited = false
             if (stop === undefined) {
+                // A wait between steps is journaled once, as it starts, and
+                // shows on the board at once: the step it waits on may run
+                // for minutes.
+                for (const wait of decided.waits) {
+                    journal.append({
+                        kind: 'ticket_waiting',
+                        ticket: wait.ticket,
+                        role: null,
+                        content: {
+                            for: wait.for,
+                            on_ticket: wait.on_ticket,
+                            since: new Date().toISOString(),
+                        },
+                    })
+                    waited = true
+                }
                 for (const action of actions) {
                     const key = keyOf(action)
                     if (!canStart({ action, key })) continue
@@ -1085,8 +373,11 @@ export const runEngine = async ({
                     if (SLOW_ACTIONS.has(action.type)) slowStarted = true
                 }
             }
-            // A slow step shows on the board while it runs, not only once it ends.
-            if (slowStarted) await board?.sync({ records: journal.read() })
+            // A slow step shows on the board while it runs, not only once it
+            // ends; so does a wait.
+            if (slowStarted || waited) {
+                await board?.sync({ records: journal.read() })
+            }
             if (inFlight.size === 0) {
                 throw new Error(
                     `The engine could start none of: ${actions.map(({ type }) => type).join(', ')}.`
@@ -1120,5 +411,7 @@ export const runEngine = async ({
         // The run ends here, so no session stays open.
         await closeFinished({ all: true })
         throw error
+    } finally {
+        live?.close()
     }
 }