@joshuafolkken/kit 1.1784.0 → 1.2114.0

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

@@ -0,0 +1,383 @@
+import { randomUUID } from 'node:crypto'
+import { setTimeout as sleep } from 'node:timers/promises'
+import { core_budget } from '#scripts/gate/core-budget'
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { process_identity } from '#scripts/josh/process-identity'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import type { LaunchResult } from '#scripts/run/detached-launch'
+import { test_pinned_ledger, type PinnedOrigin } from '#scripts/test/test-pinned-ledger'
+import { test_pinned_record, type PinnedSummary } from '#scripts/test/test-pinned-record'
+import { run_review_steps } from './run-review-steps'
+
+// The background `josh test:pinned` of `josh run:review` (joshuafolkken/kit#4770): launched beside the
+// gate and the brief, and waited on at `--join`. Run as its own `josh` command, it reserves its own
+// cores (`DIRECT_UNIT_CLAIM`), so it shares the budget with the gate's units rather than overrunning it.
+//
+// **Two records, both keyed to the checkout.** The check writes its answer under the launch's token
+// (`test-pinned-record.ts`); the start writes the launched pid and that token here, with the
+// `--unpinned-ok` reason the join judges the answer by (joshuafolkken/kit#4793). No pid means no check
+// was launched, and a pid that is gone without an answer is a check that died, which fails open the way
+// a check that could not run does.
+
+const PINNED_COMMAND = 'test:pinned'
+const LAUNCH_PREFIX = 'josh-run-review-pinned-launch-'
+const LOG_PREFIX = 'josh-run-review-pinned-log-'
+const MS_PER_SECOND = 1000
+const LOST_NOTE = 'its process ended without an answer'
+const STOP_SIGNAL = 'SIGTERM'
+
+// The join waits here only once the gate has settled and the review has returned, so the grace is
+// counted from the end of the pair (joshuafolkken/kit#4794). A check still queued for its cores gets no
+// grace at all (joshuafolkken/kit#4808): it could not finish within it. **Where a read follows, neither
+// is stopped** (joshuafolkken/kit#4888): the check keeps running on the tree the join read, and the note
+// names the one command that waits for its answer, so no lane runs `test:pinned` again by hand. Where
+// none follows, the late check is stopped rather than left holding cores.
+const GRACE_MS = 120_000
+const READ_COMMAND = 'pnpm josh run:review --pinned'
+const STILL_RUNNING_NOTE = `it is still running on this tree; wait for its answer with \`${READ_COMMAND}\` (a lane child: the ship's pre-detach reads it)`
+const TIMED_OUT_NOTE = `no answer within ${String(GRACE_MS / MS_PER_SECOND)}s of the gate and the review`
+const QUEUED_NOTE = 'it was still waiting for cores when the gate and the review ended'
+// A round 1 with fixes to make moves the tree, and the round's `josh review:record` starts the check
+// again on the fixed one — a lane child runs no `josh check:related` after the fixes
+// (joshuafolkken/kit#4983) — so the join waits no grace on this tree's (joshuafolkken/kit#4895).
+const FIXING_NOTE =
+	"round 1 has fixes to make — it is left running, and the round's `josh review:record` starts it again on the fixed tree for the ship's pre-detach to read"
+// `josh run:review --pinned` reads a check `josh review:record` started seconds before
+// (joshuafolkken/kit#4834), so it waits through the core queue and the whole run; the bound only
+// stops a check that hung.
+const ALONE_GRACE_MS = 900_000
+const ALONE_TIMED_OUT_NOTE = `no answer within ${String(ALONE_GRACE_MS / MS_PER_SECOND)}s of the read`
+
+type Clock = () => number
+
+// `start` is the launched pid's start time, so a pid the OS has since reissued is told apart from the
+// check (joshuafolkken/kit#4828). `tree` is the digest of the tree it checks (`run-review-pinned-tree.ts`),
+// so `josh review:record` tells a round-1 fix that moved the tree (joshuafolkken/kit#4834).
+// `launched_at` is the launch's epoch milliseconds, the start of a stopped check's wall time; `origin`
+// its launcher, the one a stopped check's ledger row names (joshuafolkken/kit#5327).
+interface Launch {
+	pid: number
+	token: string
+	reason?: string | undefined
+	start?: string | undefined
+	tree?: string | undefined
+	launched_at?: number | undefined
+	origin?: PinnedOrigin | undefined
+}
+
+function launch_path(root: string = PROJECT_ROOT): string {
+	return stamp_file.stamp_path(LAUNCH_PREFIX, root)
+}
+
+function log_path(root: string = PROJECT_ROOT): string {
+	return stamp_file.stamp_path(LOG_PREFIX, root, '.log')
+}
+
+interface LaunchOptions {
+	root: string
+	token: string
+	argv: Array<string>
+	origin: PinnedOrigin
+	reason?: string | undefined
+	tree?: string | undefined
+}
+
+function launch_with({ root, token, argv, origin, reason, tree }: LaunchOptions): LaunchResult {
+	const launched = run_review_steps.launch_josh(argv, log_path(root), root)
+
+	if (launched.kind === 'launched') {
+		const { pid } = launched
+
+		stamp_file.write_stamp(launch_path(root), {
+			pid,
+			token,
+			reason,
+			start: process_identity.read_start(pid),
+			tree,
+			launched_at: Date.now(),
+			origin,
+		})
+	}
+
+	return launched
+}
+
+// The token ties the answer to this launch (`test-pinned-record.ts`).
+function launch(root: string = PROJECT_ROOT, reason?: string, tree?: string): LaunchResult {
+	const token = randomUUID()
+	const origin = test_pinned_ledger.BACKGROUND_ORIGIN
+	const argv = test_pinned_record.launch_argv(token, reason, origin)
+
+	return launch_with({ root, token, argv, origin, reason, tree })
+}
+
+// **A pre-detach that stopped at its first unpinned hunk goes on probing the rest here**
+// (joshuafolkken/kit#5327): every hunk, with no reason, on the stamp `launch` writes, so the next
+// 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 argv = test_pinned_record.launch_argv(token, undefined, origin, true)
+
+	return launch_with({ root, token, argv, origin, tree })
+}
+
+function optional_text(value: unknown): string | undefined {
+	return typeof value === 'string' ? value : undefined
+}
+
+// A stamp written before `origin` was kept names none; its stop is written as `run:review`'s.
+function origin_of(value: unknown): PinnedOrigin | undefined {
+	return typeof value === 'string' ? test_pinned_ledger.origin_of(value) : undefined
+}
+
+function to_launch(value: unknown): Launch | undefined {
+	const { pid, token, reason, start, tree, launched_at, origin } = value as Record<string, unknown>
+	if (typeof pid !== 'number' || typeof token !== 'string') return undefined
+
+	return {
+		pid,
+		token,
+		reason: optional_text(reason),
+		start: optional_text(start),
+		tree: optional_text(tree),
+		launched_at: typeof launched_at === 'number' ? launched_at : undefined,
+		origin: origin_of(origin),
+	}
+}
+
+function read_launch(root: string): Launch | undefined {
+	const raw = stamp_file.read_stamp_text(launch_path(root))
+
+	if (raw === undefined) return undefined
+
+	try {
+		return to_launch(JSON.parse(raw))
+	} catch {
+		return undefined
+	}
+}
+
+// One read: the answer, `undefined` while the check is still running, or a not-run answer once its
+// process is gone without one. The record is read again after the pid is found gone, because the
+// check writes its answer before it exits.
+function read_answer(root: string, { pid, token, start }: Launch): PinnedSummary | undefined {
+	const summary = test_pinned_record.read(token, root)
+
+	if (summary !== undefined) return summary
+	if (process_identity.is_same_process(pid, start) !== false) return undefined
+
+	return (
+		test_pinned_record.read(token, root) ?? test_pinned_record.not_run_summary(new Error(LOST_NOTE))
+	)
+}
+
+// The launch is detached, so its pid leads a process group holding the `josh` process and its Vitest
+// workers; signalling the group stops them all, and `base-tree.ts` removes the trees they held.
+function signal_group(pid: number): void {
+	try {
+		process.kill(-pid, STOP_SIGNAL)
+	} catch {
+		// It ended between the check and the signal; there is nothing left to stop.
+	}
+}
+
+// **A check stopped while it runs is a discarded probe** (joshuafolkken/kit#5262): it writes no ledger
+// row of its own, so the stop writes one with the wall time it ran. A launch stamped before
+// `launched_at` has no wall time, and writes none.
+function discard(launched: Launch): void {
+	signal_group(launched.pid)
+	if (launched.launched_at === undefined) return
+
+	void test_pinned_ledger.record_discarded(Date.now() - launched.launched_at, launched.origin)
+}
+
+// A stale stamp can outlive its check by days, so the start signals only a pid whose start time
+// matches the launch's: a reissued pid, or one whose start could not be read, may lead another
+// lane's group.
+function stop_last(launched: Launch): void {
+	if (process_identity.is_same_process(launched.pid, launched.start) === true) discard(launched)
+}
+
+// The stamp a waiter just read is this pair's, minutes old, so the lone read and a supervised join
+// signal any pid not proven gone: one whose start could not be read (no `/proc`, no `ps`) is the check
+// they have just been waiting on.
+function stop_current(launched: Launch): void {
+	if (process_identity.is_same_process(launched.pid, launched.start) !== false) discard(launched)
+}
+
+// Every start stops the last pair's check and clears its records first, so a join never reads an
+// earlier tree's answer and a reopened pair leaves no check running unowned (joshuafolkken/kit#4828).
+function clear(root: string = PROJECT_ROOT): void {
+	const last = read_launch(root)
+
+	if (last !== undefined) {
+		stop_last(last)
+		test_pinned_record.clear(last.token, root)
+	}
+
+	stamp_file.remove_stamp(launch_path(root))
+}
+
+// The dispatcher's claim in the core ledger (`core-budget.ts`) carries `admitted_at` from the moment
+// the check is granted its cores, before its script even boots, so a claim from this checkout not yet
+// admitted is a check still queued. A check that claimed nothing (a parent held the cores) is not one.
+function is_queued(root: string): boolean {
+	return core_budget
+		.live_reservations()
+		.some(
+			({ reservation }) =>
+				reservation.command === PINNED_COMMAND &&
+				reservation.checkout === root &&
+				reservation.admitted_at === undefined,
+		)
+}
+
+// A check given up on fails open and is stopped rather than left burning the cores.
+function stopped(launched: Launch, note: string): PinnedSummary {
+	stop_current(launched)
+
+	return test_pinned_record.not_run_summary(new Error(note))
+}
+
+async function poll_within_grace(
+	root: string,
+	launched: Launch,
+	now: Clock,
+	grace_ms: number = GRACE_MS,
+): Promise<PinnedSummary | undefined> {
+	const started = now()
+	let summary = read_answer(root, launched)
+
+	while (summary === undefined && now() - started < grace_ms) {
+		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
+		await sleep(run_review_steps.POLL_INTERVAL_MS)
+		summary = read_answer(root, launched)
+	}
+
+	return summary
+}
+
+function given_up(launched: Launch, note: string, is_left_running: boolean): PinnedSummary {
+	if (!is_left_running) return stopped(launched, note)
+
+	return test_pinned_record.not_run_summary(new Error(`${note} — ${STILL_RUNNING_NOTE}`))
+}
+
+// The check usually settles while the review is still running; the grace only bounds the join's wait
+// on one that fell far behind the pair while running its tests.
+async function poll_answer(
+	root: string,
+	launched: Launch,
+	now: Clock,
+	is_left_running: boolean,
+): Promise<PinnedSummary> {
+	const summary = read_answer(root, launched)
+
+	if (summary !== undefined) return summary
+	if (is_queued(root)) return given_up(launched, QUEUED_NOTE, is_left_running)
+	const late = await poll_within_grace(root, launched, now)
+
+	return late ?? given_up(launched, TIMED_OUT_NOTE, is_left_running)
+}
+
+// The `--unpinned-ok` reason the last check was launched with; `undefined` when it carried none.
+function launched_reason(root: string = PROJECT_ROOT): string | undefined {
+	return read_launch(root)?.reason
+}
+
+// A reason given after the check ended (joshuafolkken/kit#4920) goes on its launch record, so a later
+// restart on a moved tree carries it as a launch's own reason does.
+function carry_reason(reason: string, root: string = PROJECT_ROOT): void {
+	const launched = read_launch(root)
+
+	if (launched !== undefined) stamp_file.write_stamp(launch_path(root), { ...launched, reason })
+}
+
+// The tree the last check was launched on; `undefined` when none was, or its tree could not be read.
+function launched_tree(root: string = PROJECT_ROOT): string | undefined {
+	return read_launch(root)?.tree
+}
+
+// `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,
+	now: Clock = () => Date.now(),
+	is_left_running = true,
+): Promise<PinnedSummary | undefined> {
+	const launched = read_launch(root)
+
+	if (launched === undefined) return undefined
+
+	return await poll_answer(root, launched, now, is_left_running)
+}
+
+// The answer as it stands, waiting nothing and stopping nothing; `undefined` when no check was launched.
+// A check still running answers with `pending_note`, why it was not waited on.
+function answer_now(
+	root: string = PROJECT_ROOT,
+	pending_note: string = FIXING_NOTE,
+): PinnedSummary | undefined {
+	const launched = read_launch(root)
+
+	if (launched === undefined) return undefined
+
+	return read_answer(root, launched) ?? test_pinned_record.not_run_summary(new Error(pending_note))
+}
+
+// Whether the last check left its answer, rather than ending without one or never being launched.
+function is_answered(root: string = PROJECT_ROOT): boolean {
+	const launched = read_launch(root)
+
+	return launched !== undefined && test_pinned_record.read(launched.token, root) !== undefined
+}
+
+// Whether a check was launched and has no answer yet: still running, rather than done or lost.
+function is_pending(root: string = PROJECT_ROOT): boolean {
+	const launched = read_launch(root)
+
+	return launched !== undefined && read_answer(root, launched) === undefined
+}
+
+// Whether the last check's process is proven to be the one launched, as `stop_last` asks before it
+// signals: a stale stamp's reissued or unreadable pid is not waited on.
+function is_live(root: string = PROJECT_ROOT): boolean {
+	const launched = read_launch(root)
+
+	return (
+		launched !== undefined &&
+		process_identity.is_same_process(launched.pid, launched.start) === true
+	)
+}
+
+// The lone read's wait: a queued check is waited on, not stopped. `undefined` when no check was launched.
+async function wait_alone(
+	root: string = PROJECT_ROOT,
+	now: Clock = () => Date.now(),
+): Promise<PinnedSummary | undefined> {
+	const launched = read_launch(root)
+
+	if (launched === undefined) return undefined
+	const summary = await poll_within_grace(root, launched, now, ALONE_GRACE_MS)
+
+	return summary ?? stopped(launched, ALONE_TIMED_OUT_NOTE)
+}
+
+const run_review_pinned_steps = {
+	FIXING_NOTE,
+	answer_now,
+	carry_reason,
+	clear,
+	is_answered,
+	is_live,
+	is_pending,
+	launch,
+	launch_remaining,
+	launched_reason,
+	launched_tree,
+	log_path,
+	wait_alone,
+	wait_for_answer,
+}
+
+export { run_review_pinned_steps }

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

@@ -0,0 +1,37 @@
+import { createHash } from 'node:crypto'
+import { gate_tree, type GateTree } from '#scripts/gate/gate-tree'
+import { run_record_path } from '#scripts/josh/run-record-path'
+
+// The tree a background `josh test:pinned` was launched on, as one digest (joshuafolkken/kit#4834):
+// `josh run:review` writes it on the launch record, and `josh review:record` compares the fixed tree
+// with it, so a round-1 fix that moved the tree starts the check again before the ship's pre-detach
+// reads it. Read from the same changed-file map and base the gate stamps (`gate-tree.ts`).
+//
+// **A reading git could not answer is no key.** An empty map or an unresolved base is not a tree, and
+// two of them would compare equal; the caller treats a missing key as "cannot tell" and starts nothing.
+//
+// **A run's own record is not the tree** (joshuafolkken/kit#5002): an observation line or a `josh
+// metrics` approval written after the launch is read by no test, so it leaves the key — and the
+// launch's answer — as it was (`run-record-path.ts`, the rule the verdict cache reads too).
+
+function digest_of({ files, base }: GateTree): string | undefined {
+	const entries = Object.entries(files)
+
+	if (base === undefined || entries.length === 0) return undefined
+
+	const code = entries
+		.filter(([file]) => !run_record_path.is_run_record(file))
+		.toSorted(([left], [right]) => left.localeCompare(right))
+
+	return createHash('sha256')
+		.update(JSON.stringify([base, code]))
+		.digest('hex')
+}
+
+async function key(): Promise<string | undefined> {
+	return digest_of(await gate_tree.read_gate_tree())
+}
+
+const run_review_pinned_tree = { digest_of, key }
+
+export { run_review_pinned_tree }

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

@@ -0,0 +1,53 @@
+import { test_pinned_logic } from '#scripts/test/test-pinned-logic'
+import type { PinnedSummary } from '#scripts/test/test-pinned-record'
+
+// The round-1 check of `josh run:review` (joshuafolkken/kit#4647): `josh test:pinned` over the change,
+// changed hunks and added files' functions alike. A change no test pins is the finding a review used
+// to stop a lane on in round 2, so the run stops on it instead, with each place listed as `file:line`.
+// It runs in the background beside the gate and the brief, and `--join` stops on its answer
+// (joshuafolkken/kit#4770), so its time leaves the critical path.
+//
+// **`--unpinned-ok "<reason>"` carries on past it** for a change no test can pin. That check runs in
+// the background too (joshuafolkken/kit#4793), so the pair never waits on it: the join prints the list
+// and the reason and carries on. **Given after the join stopped, on the same tree and a green gate,
+// the reason judges the finished answer** and re-runs neither the check nor the pair
+// (joshuafolkken/kit#4920); an answer cut at its first unpinned hunk re-runs only the whole check
+// (joshuafolkken/kit#5153). Unchecked places (over the cap, an added file `typescript` could not
+// read, or no Vitest to run a probe) never stop the run.
+
+const UNPINNED_OK_FLAG = '--unpinned-ok'
+const OK_ARGUMENT_COUNT = 2
+const STOP_NOTE =
+	'Pin each unpinned place with a test that turns red without it, then re-run `pnpm josh run:review`; for a change no test can pin, leave the tree as it is and pass the reason with `pnpm josh run:review --unpinned-ok "<reason>"` — on this tree and a green gate it judges this answer (or, cut at its first unpinned place, checks the whole change) and re-runs neither the gate nor the pair (`pnpm josh ship --review` forwards it).'
+
+type PinnedKind = 'clear' | 'stop' | 'accepted'
+
+interface PinnedVerdict {
+	kind: PinnedKind
+	text: string
+}
+
+// `--unpinned-ok` with a non-blank reason; anything else carries none.
+function ok_reason_of(argv: ReadonlyArray<string>): string | undefined {
+	const [flag, reason = ''] = argv
+	if (flag !== UNPINNED_OK_FLAG || argv.length !== OK_ARGUMENT_COUNT) return undefined
+
+	return reason.trim() === '' ? undefined : reason
+}
+
+// The join's answer on the background check, judged by the reason it was launched with; its note goes
+// above the counts line (`test_pinned_logic.report_text`), so a `tail` keeps what to do.
+function verdict_of(summary: PinnedSummary, reason: string | undefined): PinnedVerdict {
+	const { report_text } = test_pinned_logic
+
+	if (summary.unpinned.length === 0) return { kind: 'clear', text: report_text(summary) }
+	if (reason === undefined) return { kind: 'stop', text: report_text(summary, `${STOP_NOTE}\n`) }
+	const note = `Unpinned accepted by the implementer: ${reason}\n`
+
+	return { kind: 'accepted', text: report_text(summary, note) }
+}
+
+const run_review_pinned = { STOP_NOTE, UNPINNED_OK_FLAG, ok_reason_of, verdict_of }
+
+export type { PinnedVerdict }
+export { run_review_pinned }

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

@@ -3,7 +3,7 @@ import { gate_skip } from '#scripts/gate/gate-skip'
 import { gate_tree } from '#scripts/gate/gate-tree'
 import { git_location_environment } from '#scripts/git/git-location-environment'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
-import { file_map_stamp } from '#scripts/josh/file-map-stamp'
+import { file_map_stamp, type FileMapStampAccess } from '#scripts/josh/file-map-stamp'
 import { GATE_COMMAND } from '#scripts/josh/josh-command-types'
 import { stamp_file } from '#scripts/josh/stamp-file'
 import { review_stamps } from '#scripts/review/review-stamps'
@@ -12,9 +12,10 @@ import { detached_launch, type LaunchArgv, type LaunchResult } from '#scripts/ru
 import { run_review, type GateState, type ReviewTiming, type TimingStart } from './run-review'
 
 // The side effects `josh run:review` performs, kept out of `run-review.ts` the way `run-merge-steps.ts`
-// is kept out of `run-merge.ts`. Three of them: launch the gate detached so
-// one command leaves it running in the background, read back the state the join waits on from the
-// stamps a real `josh gate` writes, and keep the four timestamps the overlap is measured from.
+// is kept out of `run-merge.ts`. Three of them (the `test:pinned` check's are in
+// `run-review-pinned-steps.ts`): launch the gate detached so one command leaves it running in the
+// background, read back the state the join waits on from the stamps a real `josh gate` writes, and
+// keep the four timestamps the overlap is measured from.
 
 // Resolve `josh` through the target checkout's package script. Consumer lanes have no source entry.
 const PNPM = 'pnpm'
@@ -22,6 +23,10 @@ const DIRECTORY_FLAG = '--dir'
 const JOSH_SCRIPT = 'josh'
 const GATE_LOG_PREFIX = 'josh-run-review-gate-log-'
 const TIMING_PREFIX = 'josh-run-review-timing-'
+const START_TREE_PREFIX = 'josh-run-review-start-tree-'
+
+// The tree this pair's gate started on, which tells a moved tree from a red gate at the join.
+const start_tree_stamp: FileMapStampAccess = file_map_stamp.create(START_TREE_PREFIX, PROJECT_ROOT)
 
 // The gate is a local, no-network command that finishes in tens of seconds; the review it runs beside
 // is the longer pole, so by the time the child joins, the gate has almost always already settled. The
@@ -42,25 +47,70 @@ function timing_path(target: string = PROJECT_ROOT): string {
 // The argv is composed from constants and the validated checkout root, never interpolated into a
 // shell string — `detached_launch.launch` refuses one carrying anything a command line has no business
 // holding, and there is no shell on the path to escape from.
-function gate_argv(root: string): LaunchArgv {
+function josh_argv(root: string, josh_args: ReadonlyArray<string>): LaunchArgv {
 	return {
 		command: PNPM,
-		args: [DIRECTORY_FLAG, root, JOSH_SCRIPT, GATE_COMMAND],
+		args: [DIRECTORY_FLAG, root, JOSH_SCRIPT, ...josh_args],
 	}
 }
 
-function launch_gate(root: string = PROJECT_ROOT): LaunchResult {
+// A `josh` command left running in the background, its output kept at `log_path`: the gate, and the
+// `test:pinned` check beside it (`run-review-pinned-steps.ts`).
+function launch_josh(
+	josh_args: ReadonlyArray<string>,
+	log_path: string,
+	root: string = PROJECT_ROOT,
+): LaunchResult {
 	return detached_launch.launch(
 		{
-			argv: gate_argv(root),
+			argv: josh_argv(root, josh_args),
 			cwd: root,
-			log_path: gate_log_path(root),
+			log_path,
 			env: git_location_environment.location_free_environment(),
 		},
 		(note) => process.stderr.write(`${note}\n`),
 	)
 }
 
+function launch_gate(root: string = PROJECT_ROOT): LaunchResult {
+	return launch_josh([GATE_COMMAND], gate_log_path(root), root)
+}
+
+function to_timing(value: unknown): TimingStart | undefined {
+	if (typeof value !== 'object' || value === null) return undefined
+
+	const { gate_started_at, review_started_at } = value as Record<string, unknown>
+
+	if (typeof gate_started_at !== 'string' || typeof review_started_at !== 'string') return undefined
+
+	return { gate_started_at, review_started_at }
+}
+
+function read_timing_start(target: string = PROJECT_ROOT): TimingStart | undefined {
+	const raw = stamp_file.read_stamp_text(timing_path(target))
+
+	if (raw === undefined) return undefined
+
+	try {
+		return to_timing(JSON.parse(raw))
+	} catch {
+		return undefined
+	}
+}
+
+// **This pair's gate was green on the tree it started on** (joshuafolkken/kit#4774): a green record
+// covering that tree is one the gate either wrote or reused, and a red gate leaves only a record it
+// could not reuse — so none covers it. Read beside a record that no longer covers the current tree, it
+// is the tree that moved after the gate passed — a round-1 reviewer's fix in place — and not a red
+// gate. The record's time is no witness: a gate that reused an earlier green writes no new one.
+function is_green_on_start_tree(base: string | undefined): boolean {
+	const start = start_tree_stamp.read()
+
+	if (start === undefined) return false
+
+	return gate_skip.reusable_green_gate(start.files, base) !== undefined
+}
+
 // Green wins over the marker: a gate that has recorded a green result on this tree is done however its
 // in-flight marker reads. `reusable_green_gate` is the gate's own reuse test rather than a second copy
 // of it, so the join calls a gate green on exactly the trees the gate would skip.
@@ -74,7 +124,7 @@ async function read_gate_state(): Promise<GateState> {
 	const tree = await gate_tree.read_gate_tree()
 	const is_green = gate_skip.reusable_green_gate(tree.files, tree.base) !== undefined
 
-	return run_review.gate_state(is_green, is_running)
+	return run_review.gate_state(is_green, is_running, is_green_on_start_tree(tree.base))
 }
 
 // The brief has to report the gate as in-flight, or it says `Not verified` and sends the review agent
@@ -82,9 +132,13 @@ async function read_gate_state(): Promise<GateState> {
 // that marker itself, but its cold start can outrun the brief — so the composite writes the marker up
 // front, for the tree it is about to review. The gate overwrites it with its own identity the moment it
 // starts and clears it when it finishes, so this only closes the window between launch and that write;
-// the marker carries this process's identity, which is live while the in-process brief reads it.
+// the marker carries this process's identity, which is live while the in-process brief reads it. The
+// same tree is kept as the pair's start tree, which the gate clears no marker of.
 async function mark_gate_starting(): Promise<void> {
-	review_stamps.in_flight_stamp.write(await review_tree.read_changed_tree())
+	const tree = await review_tree.read_changed_tree()
+
+	review_stamps.in_flight_stamp.write(tree)
+	start_tree_stamp.write(tree)
 }
 
 // Waited on gate finish, for the join. The review is the longer pole, so this usually returns on its
@@ -111,28 +165,6 @@ function write_timing_start(start: TimingStart, target: string = PROJECT_ROOT):
 	stamp_file.write_stamp(timing_path(target), start)
 }
 
-function to_timing(value: unknown): TimingStart | undefined {
-	if (typeof value !== 'object' || value === null) return undefined
-
-	const { gate_started_at, review_started_at } = value as Record<string, unknown>
-
-	if (typeof gate_started_at !== 'string' || typeof review_started_at !== 'string') return undefined
-
-	return { gate_started_at, review_started_at }
-}
-
-function read_timing_start(target: string = PROJECT_ROOT): TimingStart | undefined {
-	const raw = stamp_file.read_stamp_text(timing_path(target))
-
-	if (raw === undefined) return undefined
-
-	try {
-		return to_timing(JSON.parse(raw))
-	} catch {
-		return undefined
-	}
-}
-
 // The two ends are stamped at the join: the review ended when the child returned from the subagent and
 // called this, and the gate ended at the green stamp's time where it passed, or now where it did not.
 function complete_timing(
@@ -147,13 +179,17 @@ function complete_timing(
 }
 
 const run_review_steps = {
+	MAX_JOIN_WAIT_MS,
+	POLL_INTERVAL_MS,
 	complete_timing,
 	gate_log_path,
 	launch_gate,
+	launch_josh,
 	mark_gate_starting,
 	read_gate_log,
 	read_gate_state,
 	read_timing_start,
+	start_tree_stamp,
 	timing_path,
 	wait_for_gate_finish,
 	write_timing_start,