@joshuafolkken/kit 1.3041.0 → 1.3092.0

package/scripts/run/prime/run-prime-cli.ts

@@ -2,6 +2,7 @@
 import { fileURLToPath } from 'node:url'
 import { backlog_drive_launch } from '#scripts/backlog/backlog-drive-launch'
 import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
+import { run_startup } from '#scripts/run/startup/run-startup'
 
 // `josh run:prime` — what a backlogrun owes once per repository before its first lane opens, in one
 // call (`backlogrun-lanes.md` → "Once per repository, before the first lane opens"): `main:sync`,
@@ -30,7 +31,13 @@ function first_line(result: JoshResult): string {
 
 // `undefined` once the step failed, its failure named on stderr.
 async function step(argv: ReadonlyArray<string>): Promise<JoshResult | undefined> {
-	const result = await josh_command.josh_run(argv, should_forward_stderr)
+	const result = await run_startup.phase(
+		`initialization ${argv[0] ?? ''}`,
+		async () => await josh_command.josh_run(argv, should_forward_stderr),
+		{
+			edge_of: (value) => (value.code === SUCCESS_EXIT_CODE ? 'done' : 'failed'),
+		},
+	)
 
 	if (result.out !== '') console.error(result.out)
 	if (result.code === SUCCESS_EXIT_CODE) return result
@@ -93,7 +100,14 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 		return FAILURE_EXIT_CODE
 	}
 
-	return (await primed()) ? await sweep() : FAILURE_EXIT_CODE
+	return await run_startup.phase(
+		'initialization',
+		async () => ((await primed()) ? await sweep() : FAILURE_EXIT_CODE),
+		{
+			root: true,
+			edge_of: (value) => (value === SUCCESS_EXIT_CODE ? 'done' : 'failed'),
+		},
+	)
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) {

package/scripts/run/review/run-review-cli.ts

@@ -54,7 +54,7 @@ import { run_review_unplanned } from './run-review-unplanned'
 // `josh check:related` before its round is recorded, joshuafolkken/kit#4948) starts it again on a tree a round-1 fix
 // moved, after the join has closed the pair, and reads its answer without joining a gate that already
 // settled. The ship's pre-detach reads that answer anyway, so a lane need not
-// (joshuafolkken/kit#4895), and a lane child's `--pinned` returns at once rather than wait in the
+// (joshuafolkken/kit#4895), and a lane child's `--pinned` returns at once except for a ship's remaining
 // foreground (joshuafolkken/kit#5293). **`--join --fixing` waits no grace on the check**: round 1's fixes will move
 // its tree. **A lane child's open commits first and `--push` pushes at the green gate**
 // (`run-review-early-push.ts`).
@@ -181,7 +181,7 @@ function join_hint(slots: ReadonlyArray<ReviewSlot>): string {
 // The early push waits on the gate this pair launched, so it follows a written brief alone.
 function follow_brief(slots: ReadonlyArray<ReviewSlot>, is_early_push: boolean): void {
 	process.stderr.write(`${join_hint(slots)}\n`)
-	if (is_early_push) run_review_early_push.launch()
+	if (is_early_push) run_review_early_push.launch(slots.length)
 }
 
 const GREEN_NOTE = 'Gate green — the review verdict may be adopted.'
@@ -441,15 +441,13 @@ async function run_open(is_code_only: boolean, argv: ReadonlyArray<string>): Pro
 }
 
 async function run_pinned(): Promise<number> {
-	if (lane_child_marker.is_child_of(process.cwd())) {
+	if (lane_child_marker.is_child_of(process.cwd()) && !run_review_pinned_steps.is_remaining()) {
 		process.stdout.write(`${LANE_PINNED_NOTE}\n`)
 
 		return SUCCESS_EXIT_CODE
 	}
 
-	const is_unpinned = await show_pinned(
-		run_review_join_read.read_with(run_review_pinned_steps.wait_alone),
-	)
+	const is_unpinned = await show_pinned(run_review_join_read.read_remaining())
 
 	return is_unpinned ? run_review.UNPINNED_EXIT_CODE : SUCCESS_EXIT_CODE
 }
@@ -459,13 +457,13 @@ const LONE_MODES: ReadonlyMap<string, () => Promise<number>> = new Map([
 	[JOIN_FLAG, run_join],
 	[`${JOIN_FLAG} ${FIXING_FLAG}`, run_join_fixing],
 	[PINNED_FLAG, run_pinned],
-	[run_review_early_push.PUSH_FLAG, run_review_early_push.push],
 ])
 
 async function run(argv: ReadonlyArray<string>): Promise<number> {
 	const lone = LONE_MODES.get(argv.join(' '))
 
 	if (lone !== undefined) return await lone()
+	if (argv[0] === run_review_early_push.PUSH_FLAG) return await run_review_early_push.push(argv[1])
 	const is_code_only = argv[0] === run_review.CODE_ONLY_FLAG
 
 	return await run_open(is_code_only, argv.slice(is_code_only ? 1 : 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 {