@joshuafolkken/kit 1.3044.0 → 1.3099.0

package/scripts/run/review/run-review-early-push.ts

@@ -87,28 +87,37 @@ async function prepare(
 	directory?: string,
 ): Promise<boolean> {
 	const reason = preparation_skip(plan, environment ?? process.env, directory ?? PROJECT_ROOT)
+	const slots = plan.slots.length
 
 	if (reason !== undefined) {
-		await early_push_record.record('review', reason)
+		await early_push_record.record('review', reason, slots)
 
 		return false
 	}
 
 	const is_committed = await commit_locally()
 
-	if (!is_committed) await early_push_record.record('review', 'commit-refused')
+	if (!is_committed) await early_push_record.record('review', 'commit-refused', slots)
 
 	return is_committed
 }
 
-function launch(): void {
+// The background push records the round's slot count, so it rides on the argv.
+function launch(slots: number): void {
 	const log_path = stamp_file.stamp_path(PUSH_LOG_PREFIX, PROJECT_ROOT)
-	const result = run_review_steps.launch_josh([RUN_REVIEW_COMMAND, PUSH_FLAG], log_path)
+	const argv = [RUN_REVIEW_COMMAND, PUSH_FLAG, String(slots)]
+	const result = run_review_steps.launch_josh(argv, log_path)
 
 	if (result.kind !== 'failed') return
 
 	process.stderr.write(`${SKIPPED_NOTE}the push could not be started: ${result.note}\n`)
-	void early_push_record.record('review', 'launch-failed')
+	void early_push_record.record('review', 'launch-failed', slots)
+}
+
+function slot_count(argument: string | undefined): number | undefined {
+	const slots = Number(argument)
+
+	return Number.isSafeInteger(slots) && slots > 0 ? slots : undefined
 }
 
 async function skip_reason(): Promise<string | undefined> {
@@ -127,13 +136,14 @@ async function body_arguments(): Promise<ReadonlyArray<string>> {
 	return run_ship_body_draft.body_arguments(draft)
 }
 
-// `josh run:review --push`, the background half: a skipped push exits 0, as nothing failed.
-async function push(): Promise<number> {
+// `josh run:review --push <slots>`, the background half: a skipped push exits 0, as nothing failed.
+async function push(slots_argument?: string): Promise<number> {
+	const slots = slot_count(slots_argument)
 	const reason = await skip_reason()
 
 	if (reason !== undefined) {
 		process.stdout.write(`${SKIPPED_NOTE}${reason === DIRTY_REASON ? DIRTY_NOTE : RED_NOTE}\n`)
-		await early_push_record.record('review', reason)
+		await early_push_record.record('review', reason, slots)
 
 		return SUCCESS_EXIT_CODE
 	}
@@ -143,6 +153,7 @@ async function push(): Promise<number> {
 	await early_push_record.record(
 		'review',
 		result.code === SUCCESS_EXIT_CODE ? 'pushed' : 'push-failed',
+		slots,
 	)
 
 	process.stdout.write(`${result.out}\n`)

package/scripts/run/review/run-review-join-read.ts

@@ -5,6 +5,7 @@ import { test_pinned_logic } from '#scripts/test/test-pinned-logic'
 import type { PinnedSummary } from '#scripts/test/test-pinned-record'
 import { run_review_pinned_accepted } from './run-review-pinned-accepted'
 import { run_review_pinned_join } from './run-review-pinned-join'
+import { run_review_pinned_remaining } from './run-review-pinned-remaining'
 import { run_review_pinned_steps } from './run-review-pinned-steps'
 
 // The read of `josh run:review --join` on the background `josh test:pinned` (joshuafolkken/kit#5212).
@@ -76,19 +77,45 @@ async function read(
 	is_fixing = false,
 ): Promise<JoinVerdict | undefined> {
 	return await read_with(
-		async () => await run_review_pinned_join.wait_for_join(root, undefined, is_fixing),
+		async () =>
+			await run_review_pinned_remaining.collect(
+				await run_review_pinned_join.wait_for_join(root, undefined, is_fixing),
+				root,
+			),
 		root,
 	)
 }
 
-// `review:record`'s read: only an answer already left on this very tree
-// (`run_review_pinned_join.finished_on_tree`). It neither waits (joshuafolkken/kit#4895) nor starts a
-// check, so the restart that follows on a moved tree still says who reads its answer.
+// Record collects an existing remaining probe, but never waits for a fresh round-1 check.
 async function read_finished(root: string = PROJECT_ROOT): Promise<JoinVerdict | undefined> {
-	return await read_with(async () => await run_review_pinned_join.finished_on_tree(root), root)
+	return await read_with(
+		async () =>
+			(await run_review_pinned_remaining.read(root)) ??
+			(await run_review_pinned_remaining.collect(
+				await run_review_pinned_join.finished_on_tree(root),
+				root,
+			)),
+		root,
+	)
+}
+
+async function read_remaining(): Promise<JoinVerdict | undefined> {
+	return await read_with(
+		async () =>
+			(await run_review_pinned_remaining.read()) ??
+			(await run_review_pinned_remaining.collect(await run_review_pinned_steps.wait_alone())),
+	)
 }
 
-const run_review_join_read = { is_due, mark_due, read, read_finished, read_with, verdict }
+const run_review_join_read = {
+	is_due,
+	mark_due,
+	read,
+	read_finished,
+	read_remaining,
+	read_with,
+	verdict,
+}
 
 export type { JoinVerdict, PinnedWait }
 export { run_review_join_read }

package/scripts/run/review/run-review-pinned-remaining.ts

@@ -0,0 +1,124 @@
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { error_text } from '#scripts/lib/error-message'
+import type { LaunchResult } from '#scripts/run/detached-launch'
+import { test_pinned } from '#scripts/test/test-pinned'
+import { test_pinned_logic } from '#scripts/test/test-pinned-logic'
+import { test_pinned_record, type PinnedSummary } from '#scripts/test/test-pinned-record'
+import { run_review_pinned_join } from './run-review-pinned-join'
+import { run_review_pinned_steps } from './run-review-pinned-steps'
+import { run_review_pinned_tree } from './run-review-pinned-tree'
+
+const MOVED_NOTE = 'the tree moved while collecting remaining verdicts'
+
+async function is_current(tree: string | undefined): Promise<boolean> {
+	return tree !== undefined && tree === (await run_review_pinned_tree.key())
+}
+
+// Use the existing continuation's launch/record/cache. Ship keeps its first stop; the next join
+// or record collects the rest before fixes move the tree (joshuafolkken/kit#7438).
+async function start(root: string = PROJECT_ROOT): Promise<LaunchResult> {
+	try {
+		const tree = await run_review_pinned_tree.key()
+
+		if (tree === undefined) return { kind: 'failed', note: 'could not read the current tree' }
+		run_review_pinned_steps.clear(root)
+
+		return run_review_pinned_steps.launch_remaining(root, tree)
+	} catch (error) {
+		error_text.trace_swallowed('run_review_pinned_remaining.start', error)
+
+		return { kind: 'failed', note: String(error) }
+	}
+}
+
+function is_failed(summary: PinnedSummary | undefined): summary is PinnedSummary {
+	return summary?.counts === undefined && summary?.is_unchecked === true
+}
+
+async function recover_failed(summary: PinnedSummary, root: string): Promise<PinnedSummary> {
+	try {
+		const report = await test_pinned.cached(test_pinned_logic.DEFAULT_MAX_HUNKS)
+
+		if (report.is_stale === true || report.unpinned.length === 0) return summary
+		const known = test_pinned_record.summary_of(report, root)
+
+		return { ...known, is_cut: true, is_unchecked: true, text: `${known.text}${summary.text}` }
+	} catch (error) {
+		error_text.trace_swallowed('run_review_pinned_remaining.recover_failed', error)
+
+		return summary
+	}
+}
+
+async function current_answer(root: string): Promise<PinnedSummary | undefined> {
+	const summary = await run_review_pinned_steps.wait_alone(root)
+	const tree = await run_review_pinned_tree.key()
+
+	if (tree === undefined || run_review_pinned_steps.launched_tree(root) !== tree) {
+		return test_pinned_record.not_run_summary(MOVED_NOTE)
+	}
+
+	const answer = is_failed(summary) ? await recover_failed(summary, root) : summary
+
+	return (await is_current(tree)) ? answer : test_pinned_record.not_run_summary(MOVED_NOTE)
+}
+
+async function relaunched_answer(root: string): Promise<PinnedSummary | undefined> {
+	const launched = await start(root)
+
+	return launched.kind === 'launched'
+		? await current_answer(root)
+		: test_pinned_record.not_run_summary(launched.note)
+}
+
+// Settle an old tree into the cache first; only cache misses are probed on the current tree.
+async function read(root: string = PROJECT_ROOT): Promise<PinnedSummary | undefined> {
+	if (!run_review_pinned_steps.is_remaining(root)) return undefined
+
+	if (run_review_pinned_steps.launched_tree(root) === (await run_review_pinned_tree.key())) {
+		return await current_answer(root)
+	}
+
+	return (await run_review_pinned_join.answer_on_tree(root)) ?? (await relaunched_answer(root))
+}
+
+function incomplete(summary: PinnedSummary): PinnedSummary {
+	return {
+		...summary,
+		text: `${summary.text}Remaining probe incomplete: no current-tree answer\n`,
+	}
+}
+
+function collected(summary: PinnedSummary, answer: PinnedSummary | undefined): PinnedSummary {
+	if (answer === undefined) return incomplete(summary)
+
+	return answer.counts === undefined && answer.is_unchecked === true
+		? { ...summary, text: `${summary.text}${answer.text}` }
+		: answer
+}
+
+function is_collectable(summary: PinnedSummary, root: string): boolean {
+	return summary.is_cut === true && run_review_pinned_steps.launched_reason(root) === undefined
+}
+
+async function collect_current(summary: PinnedSummary, root: string): Promise<PinnedSummary> {
+	const tree = await run_review_pinned_tree.key()
+	const answer = (await read(root)) ?? (await relaunched_answer(root))
+
+	return (await is_current(tree))
+		? collected(summary, answer)
+		: test_pinned_record.not_run_summary(MOVED_NOTE)
+}
+
+async function collect(
+	summary: PinnedSummary | undefined,
+	root: string = PROJECT_ROOT,
+): Promise<PinnedSummary | undefined> {
+	return summary !== undefined && is_collectable(summary, root)
+		? await collect_current(summary, root)
+		: summary
+}
+
+const run_review_pinned_remaining = { collect, read, start }
+
+export { run_review_pinned_remaining }

package/scripts/run/review/run-review-pinned-steps.ts

@@ -21,6 +21,7 @@ import { run_review_steps } from './run-review-steps'
 // a check that could not run does.
 
 const PINNED_COMMAND = 'test:pinned'
+const REMAINING_ORIGIN: PinnedOrigin = 'pre-detach'
 const LAUNCH_PREFIX = 'josh-run-review-pinned-launch-'
 const LOG_PREFIX = 'josh-run-review-pinned-log-'
 const MS_PER_SECOND = 1000
@@ -117,7 +118,7 @@ function launch(root: string = PROJECT_ROOT, reason?: string, tree?: string): La
 // pre-detach joins it (`run-review-pinned-join.ts`) and `clear` discards it as it does that one.
 function launch_remaining(root: string = PROJECT_ROOT, tree?: string): LaunchResult {
 	const token = randomUUID()
-	const origin: PinnedOrigin = 'pre-detach'
+	const origin = REMAINING_ORIGIN
 	const argv = test_pinned_record.launch_argv(token, undefined, origin, true)
 
 	return launch_with({ root, token, argv, origin, tree })
@@ -304,6 +305,10 @@ function launched_tree(root: string = PROJECT_ROOT): string | undefined {
 	return read_launch(root)?.tree
 }
 
+function is_remaining(root: string = PROJECT_ROOT): boolean {
+	return read_launch(root)?.origin === REMAINING_ORIGIN
+}
+
 // `undefined` when no check was launched. `is_left_running` is false where nothing reads a late answer.
 async function wait_for_answer(
 	root: string = PROJECT_ROOT,
@@ -376,6 +381,7 @@ const run_review_pinned_steps = {
 	is_answered,
 	is_live,
 	is_pending,
+	is_remaining,
 	launch,
 	launch_remaining,
 	launched_reason,

package/scripts/run/run-halfrun-resume.ts

@@ -1,3 +1,4 @@
+import { session_cite } from '#scripts/issue/session-cite'
 import { lane_state } from '#scripts/lane/lane-state'
 import {
 	run_hold,
@@ -29,10 +30,14 @@ function hold_of(read: HoldRead): RunHold | undefined {
 	return read.kind === 'held' || read.kind === 'stale' ? read.hold : undefined
 }
 
-function is_halfrun_stop(read: HoldRead, issue: string, is_dirty: boolean): boolean {
+function is_stop_record(read: HoldRead, issue: string): boolean {
 	const hold = hold_of(read)
 
-	return is_dirty && hold?.issue === issue && hold.is_halfrun_stop === true
+	return hold?.issue === issue && hold.is_halfrun_stop === true
+}
+
+function is_halfrun_stop(read: HoldRead, issue: string, is_dirty: boolean): boolean {
+	return is_dirty && is_stop_record(read, issue)
 }
 
 // The stopping run's own record names its issue, or `new` when it entered as `halfrun new`; a free tree
@@ -68,6 +73,44 @@ function take_over(target: string, issue: string): boolean {
 	return run_hold.create_hold(target, issue, new Date(), true)
 }
 
+// **A fix round re-opens the stop** (`run:hold <N> --halfrun-round`, joshuafolkken/kit#7494): the person
+// came back with fixes, so the stopped record is replaced by a running `halfrun`'s owned by the round's
+// session — `run:board` draws the round and `tree:status` names its process — until the round's own
+// `--halfrun-stop` marks it again. `MARKED` here is the record written; only #N's own stop qualifies.
+function reopen_at(target: string, issue: string): StopMark {
+	const read = run_hold.read_hold(target)
+
+	if (read.kind === 'unreadable') return UNREADABLE
+
+	if (!is_stop_record(read, issue)) return FOREIGN
+
+	run_hold.release_hold(target)
+
+	return run_hold.create_hold(target, issue) ? MARKED : FOREIGN
+}
+
+// A stop picked up again is running, so a `human-review` lane is returned to `running` — else lane
+// readers count the round's tree as idle while the board draws it running.
+async function resume_lane(issue: string, command: string): Promise<void> {
+	const lane = await lane_state.read_state(issue)
+
+	if (lane?.state === 'human-review') {
+		await lane_state.record_change({ issue, state: 'running', command })
+	}
+}
+
+async function reopen(target: string, issue: string): Promise<StopMark> {
+	const mark = reopen_at(target, issue)
+
+	if (mark === MARKED) await resume_lane(issue, 'run:hold --halfrun-round')
+
+	return mark
+}
+
+function no_stop_message(issue: string): string {
+	return `run:hold: this tree holds no stopped \`halfrun\` of ${session_cite.issue(issue)} — a fix round re-opens only that record.`
+}
+
 // `false` leaves the record untouched, so the ordinary claim that follows decides the tree.
 function adopt_at(target: string, issue: string, is_dirty: boolean): boolean {
 	if (!is_halfrun_stop(run_hold.read_hold(target), issue, is_dirty)) return false
@@ -102,11 +145,8 @@ async function adopt(issue: string): Promise<boolean> {
 	if (target === undefined) return false
 
 	const is_adopted = adopt_at(target, issue, await run_hold.is_tree_dirty())
-	const lane = is_adopted ? await lane_state.read_state(issue) : undefined
 
-	if (lane?.state === 'human-review') {
-		await lane_state.record_change({ issue, state: 'running', command: 'run:entry' })
-	}
+	if (is_adopted) await resume_lane(issue, 'run:entry')
 
 	return is_adopted
 }
@@ -121,6 +161,9 @@ const run_halfrun_resume = {
 	hold_target,
 	is_pending,
 	mark_stop_at,
+	no_stop_message,
+	reopen,
+	reopen_at,
 	take_over,
 }
 

package/scripts/run/run-headless.ts

@@ -2,6 +2,7 @@ import { lane_child_marker } from '#scripts/lane/lane-child-marker'
 import { lane_reap } from '#scripts/lane/lane-reap'
 import { lane_registry } from '#scripts/lane/lane-registry'
 import { run_carry, type CarryRead, type RunCarry } from '#scripts/run/carry/run-carry'
+import { run_carry_session } from '#scripts/run/carry/run-carry-session'
 import { run_headless_keys } from '#scripts/run/run-headless-keys'
 
 // The headless `backlogrun` parent. `run:wake` starts a cut's successor as
@@ -100,6 +101,8 @@ async function current_carry(): Promise<RunCarry | undefined> {
 // owner is `--owner "$PPID"`, the session process, which is an ancestor of every hook it runs; a
 // record that declared no owner proves no one is its parent.
 function is_owned_here(carry: RunCarry, ancestry: () => ReadonlySet<number>): boolean {
+	if (carry.owner_session !== undefined) return carry.owner_session === run_carry_session.own()
+
 	return carry.owner_pid !== undefined && ancestry().has(carry.owner_pid)
 }
 

package/scripts/run/run-pr-return.ts

@@ -51,8 +51,16 @@ function comments_since(
 
 // When the run last committed its own work: the newest non-merge commit on the branch's own line,
 // so a merge of main (and the commits it brings) does not move it past a comment already written.
-async function last_work_ms(): Promise<number> {
-	const date = await git_spawn.read(['log', '--first-parent', '--no-merges', '-1', '--format=%cI'])
+async function last_work_ms(directory?: string): Promise<number> {
+	const location = directory === undefined ? [] : ['-C', directory]
+	const date = await git_spawn.read([
+		...location,
+		'log',
+		'--first-parent',
+		'--no-merges',
+		'-1',
+		'--format=%cI',
+	])
 
 	return Date.parse(date)
 }
@@ -79,12 +87,13 @@ async function read_comments(issue: string): Promise<ReadonlyArray<WatchComment>
 	return (await issue_watch_diff.parse_comments(json)) ?? []
 }
 
-async function read(issue: string): Promise<PrReturn> {
-	const branch = await git_command.branch()
+async function read(issue: string, directory?: string): Promise<PrReturn> {
+	const branch =
+		directory === undefined ? await git_command.branch() : await git_command.branch_at(directory)
 	const [snapshot_json, comments, since_ms] = await Promise.all([
 		git_gh_pr_snapshot.pr_get_state_snapshot(branch),
 		read_comments(issue),
-		last_work_ms(),
+		last_work_ms(directory),
 	])
 
 	return {

package/scripts/run/run-repair-attempt.ts

@@ -0,0 +1,219 @@
+import { statSync } from 'node:fs'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { git_command } from '#scripts/git/git-command'
+import { git_common_directory } from '#scripts/git/git-common-directory'
+import { pr_info_schema } from '#scripts/git/git-schemas'
+import { repository_lock } from '#scripts/git/repository-lock'
+import { issue_state_cli } from '#scripts/issue/issue-state-cli'
+import { lane_await } from '#scripts/lane/lane-await'
+import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
+import { json_value } from '#scripts/lib/json-value'
+import { run_add } from './add/run-add'
+import { run_carry } from './carry/run-carry'
+import { run_cut } from './cut/run-cut'
+import { run_event_retry } from './event/run-event-retry'
+import { run_event_scope } from './event/run-event-scope'
+import { run_event_stream, type RunEvent } from './event/run-event-stream'
+import { run_event_stream_emit } from './event/run-event-stream-emit'
+import { run_pr_return } from './run-pr-return'
+import { run_ship_detach } from './ship/run-ship-detach'
+
+// A reviewed PR starts a repair only after the previous worker ended. The existing retry event is
+// the attempt boundary; its repair suffix makes a repeated queue request idempotent.
+const REPAIR_SUFFIX = ' repair'
+const LOCK_WAIT_MS = 5000
+const PERMANENT_KINDS: ReadonlySet<string> = new Set(['merge', 'withdraw', 'split'])
+const QUEUED_END_KINDS: ReadonlySet<string> = new Set([
+	...PERMANENT_KINDS,
+	run_event_stream.EVENT_KIND.HUMAN_REVIEW,
+	run_event_stream.EVENT_KIND.CHILD_LAUNCH,
+	run_event_stream.EVENT_KIND.PARK,
+])
+const WRITE_FAILED = 'Could not record the repair attempt boundary.'
+
+function repair_text(issue: string): string {
+	return `${run_event_retry.text_of(Number(issue))}${REPAIR_SUFFIX}`
+}
+
+function issue_attempt(events: ReadonlyArray<RunEvent>, issue: string): ReadonlyArray<RunEvent> {
+	return run_event_retry
+		.current_attempts(events)
+		.filter((event) => run_event_scope.issue_named(event) === issue)
+}
+
+function is_queued(events: ReadonlyArray<RunEvent>, issue: string): boolean {
+	return (
+		events[0]?.text === repair_text(issue) &&
+		events.every((event) => !QUEUED_END_KINDS.has(event.kind))
+	)
+}
+
+function reviewed_at(events: ReadonlyArray<RunEvent>): string | undefined {
+	if (events.some((event) => PERMANENT_KINDS.has(event.kind))) return undefined
+
+	return events.findLast((event) => event.kind === run_event_stream.EVENT_KIND.HUMAN_REVIEW)?.at
+}
+
+async function is_unprotected(issue: string): Promise<boolean> {
+	const read = await issue_state_cli.read_issue(issue)
+
+	return (
+		read.kind === 'state' &&
+		read.state.state === 'OPEN' &&
+		run_add.protected_label(read.state.labels) === undefined
+	)
+}
+
+async function is_returned(lane: LaneInfo, since: string | undefined): Promise<boolean> {
+	const raw = await git_gh_command.pr_view(lane.branch)
+
+	if (json_value.parse_with(raw, pr_info_schema)?.state !== 'OPEN') return false
+	if (since === undefined) return true
+	const returned = await run_pr_return.read(lane.issue, lane.directory)
+
+	return run_pr_return
+		.comments_since(returned.comments, Date.parse(since))
+		.some((comment) => comment.is_trusted === true)
+}
+
+function cut_target(lane: LaneInfo): string | undefined {
+	const directory = git_common_directory.own(lane.directory)
+
+	return directory === undefined ? undefined : run_cut.cut_path(directory)
+}
+
+function can_end_cut(target: string, lane: LaneInfo): boolean {
+	const read = run_cut.read_cut(target)
+
+	if (read.kind === 'none') return true
+	if (read.kind === 'unreadable') return false
+
+	return (
+		read.cut.issue === lane.issue &&
+		read.cut.branch === lane.branch &&
+		read.cut.invocation === run_cut.invocation_for(lane.issue)
+	)
+}
+
+async function append_boundary(issue: string): Promise<void> {
+	const target = await run_event_stream_emit.stream_target()
+
+	if (target === undefined) throw new Error(WRITE_FAILED)
+	const result = await run_event_stream_emit.append_at(
+		target,
+		run_event_stream.EVENT_KIND.ADD,
+		repair_text(issue),
+		new Date(),
+	)
+
+	if (!result.appended) throw new Error(WRITE_FAILED)
+}
+
+async function has_ended_ship(issue: string): Promise<boolean> {
+	const repository = await run_carry.repository_directory()
+
+	if (repository === undefined) return false
+	const info = statSync(run_ship_detach.result_path(repository, issue), { throwIfNoEntry: false })
+
+	if (info === undefined) return true
+	const result = run_ship_detach.read_result(repository, issue)
+
+	return result !== undefined && result.result !== 'running'
+}
+
+// Uncommitted work in the lane means its `in-progress` still marks a live hand-off; a tree git
+// cannot read counts as uncommitted (joshuafolkken/kit#7493).
+async function is_clean(lane: LaneInfo): Promise<boolean> {
+	try {
+		return (await git_command.status(lane.directory)) === ''
+	} catch {
+		return false
+	}
+}
+
+async function is_repairable(issue: string, lane: LaneInfo): Promise<boolean> {
+	return (await is_unprotected(issue)) && (await is_clean(lane))
+}
+
+async function ready_lane(issue: string): Promise<LaneInfo | undefined> {
+	if ((await lane_await.other_process_trace(issue)) !== 'none' || !(await has_ended_ship(issue))) {
+		return undefined
+	}
+
+	const lane = await lane_registry.find_open_lane(issue)
+
+	if (lane === undefined || !(await is_repairable(issue, lane))) return undefined
+
+	return lane
+}
+
+function eligible_cut_target(
+	lane: LaneInfo,
+	expected_target: string | undefined,
+): string | undefined {
+	const target = cut_target(lane)
+
+	if (expected_target !== undefined && expected_target !== target) return undefined
+
+	return target !== undefined && can_end_cut(target, lane) ? target : undefined
+}
+
+async function finish(
+	lane: LaneInfo,
+	events: ReadonlyArray<RunEvent>,
+	since: string | undefined,
+	expected_target: string | undefined,
+): Promise<boolean> {
+	const target = eligible_cut_target(lane, expected_target)
+
+	if (target === undefined || !(await is_returned(lane, since))) return false
+	if (!is_queued(events, lane.issue)) await append_boundary(lane.issue)
+	run_cut.end_cut(target)
+
+	return true
+}
+
+function is_candidate(events: ReadonlyArray<RunEvent>, issue: string): boolean {
+	return reviewed_at(events) !== undefined || is_queued(events, issue)
+}
+
+function checked_preparation(
+	is_prepared: boolean,
+	events: ReadonlyArray<RunEvent>,
+	issue: string,
+): boolean {
+	if (!is_prepared && is_queued(events, issue)) {
+		throw new Error('Could not safely resume the queued repair.')
+	}
+
+	return is_prepared
+}
+
+async function prepare_held(issue: string, expected_target: string | undefined): Promise<boolean> {
+	const events = issue_attempt(await run_event_stream_emit.all_events(true), issue)
+
+	if (!is_candidate(events, issue)) return false
+	const lane = await ready_lane(issue)
+
+	const is_prepared =
+		lane === undefined ? false : await finish(lane, events, reviewed_at(events), expected_target)
+
+	return checked_preparation(is_prepared, events, issue)
+}
+
+async function prepare(issue: string, expected_target?: string): Promise<boolean> {
+	const lock = repository_lock.lock_path(`josh-repair-${issue}-`)
+	const is_prepared = await repository_lock.with_lock(
+		async () => await prepare_held(issue, expected_target),
+		lock,
+		LOCK_WAIT_MS,
+	)
+
+	if (is_prepared === undefined) throw new Error('Could not lock the repair attempt.')
+
+	return is_prepared
+}
+
+const run_repair_attempt = { issue_attempt, prepare, reviewed_at }
+
+export { run_repair_attempt }