@joshuafolkken/kit 1.2116.0 → 1.3000.0

package/scripts/run/ship/run-ship-sync.ts

@@ -1,3 +1,5 @@
+import { followup_ship_environment } from '#scripts/followup/followup-ship-environment'
+import { git_gh_code_scanning } from '#scripts/gh/git-gh-code-scanning'
 import { git_gh_pr_read } from '#scripts/gh/git-gh-pr-read'
 import {
 	FAILURE_MESSAGE_PREFIX,
@@ -10,6 +12,7 @@ import { pre_commit_lint_switch } from '#scripts/hooks/pre-commit-lint-switch'
 import { pre_push_related_switch } from '#scripts/hooks/pre-push-related-switch'
 import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
 import { error_text } from '#scripts/lib/error-message'
+import { run_ship_conflict_probe } from './run-ship-conflict-probe'
 import { run_ship_lap } from './run-ship-lap'
 import { run_ship_overlap } from './run-ship-overlap'
 import { run_ship_scoped } from './run-ship-scoped'
@@ -20,8 +23,8 @@ import { run_ship_stop_cause, type Cause } from './run-ship-stop-cause'
 // merging the default branch again usually resolves it.
 //
 // So the merge happens mechanically: before the gate (`sync_stage`), again before the push when the
-// default branch moved since (`catch_up`), and when the followup fails after it moved again
-// (`followup_stage`). A conflict only on
+// default branch moved since with a conflict (`catch_up`; a clean move is left to the merge ref's CI),
+// and when the followup fails after it moved again (`followup_stage`). A conflict only on
 // the files `main-merge-regenerate.ts` lists is resolved by the merge itself; any other conflict
 // stops the ship as `conflict`, naming the unmerged paths so the resumed session goes straight to them.
 
@@ -41,6 +44,12 @@ const MERGED_GATE_NOTE =
 const PUSHED_NOTE = 'pushed the merge ahead of the gate, so CI runs beside it'
 const PUSH_FAILED_NOTE =
 	'the push ahead of the gate failed; the commit stage pushes after the gate:'
+const PAIR_RED_NOTE =
+	'the scoped pair is red on the merged tree; the commit stage pushes after the gate'
+const LEFT_TO_CI_NOTE =
+	'the default branch moved since the sync without a conflict — not merged again; the pull request CI checks the merge ref'
+const MERGED_AGAIN_NOTE =
+	'followup: the default branch moved under the failed checks — merged it again; gating and pushing the merged tree, no re-ship'
 
 // A stage's result, plus the paths a stopped merge left unmerged — carried to the stop prompt.
 // `is_skipped` marks a stage that found nothing to do — a review round with nothing to review, a gate
@@ -126,7 +135,16 @@ async function commit_locally(title: string, is_dirty: boolean): Promise<JoshRes
 // default branch pushes nothing either, so the commit stage stays the one push; a merged one makes it
 // two, and CI and the review bots run again on the second. A failed push stops nothing: the commit
 // stage pushes the gated tree.
+//
+// **The scoped pair settles before that push** (joshuafolkken/kit#6121): the merge moved the base
+// under the pair's records, so the hook's related run read none of them and re-ran tests the pair had
+// passed. A merge sharing nothing with the branch re-records the pair without a run, any other runs it
+// where the two meet, and the hook then reuses `test:related`'s record; the gate stage reuses the pair.
 async function push_ahead(title: string): Promise<string> {
+	const pair = await run_ship_scoped.scoped_pair()
+
+	if (pair.code !== SUCCESS_EXIT_CODE) return PAIR_RED_NOTE
+
 	const push = await timed(
 		STEP.PUSH,
 		async () =>
@@ -138,17 +156,18 @@ async function push_ahead(title: string): Promise<string> {
 	return push.code === SUCCESS_EXIT_CODE ? PUSHED_NOTE : [PUSH_FAILED_NOTE, push.out].join('\n')
 }
 
-// An unreadable pull request reads as none: the commit stage pushes after the gate either way.
-async function has_open_pull(): Promise<boolean> {
+// An unreadable pull request reads as none: the commit stage pushes after the gate either way, and
+// the followup merges again as it did before.
+async function open_pull_number(): Promise<number | undefined> {
 	try {
-		return (await git_gh_pr_read.pr_get_number(await git_command.branch())) !== undefined
+		return await git_gh_pr_read.pr_get_number(await git_command.branch())
 	} catch {
-		return false
+		return undefined
 	}
 }
 
 async function pushed_note(outcome: MergeOutcome, title: string): Promise<string> {
-	if (outcome.kind !== 'merged' || !(await has_open_pull())) return ''
+	if (outcome.kind !== 'merged' || (await open_pull_number()) === undefined) return ''
 
 	return await push_ahead(title)
 }
@@ -186,8 +205,9 @@ async function sync_stage(issue: string, title: string, is_dirty: boolean): Prom
 }
 
 // The tree merged with a default branch that moved is gated before it is pushed: a tree only the
-// combined change breaks — two lanes each growing one document inside its cap — stops here, reproduced
-// locally rather than met on CI's merge ref (joshuafolkken/kit#4825). The push then carries the tree
+// combined change breaks — two lanes each growing one document inside its cap — stops here
+// (joshuafolkken/kit#4825); a clean move over a green gate skips this merge and leaves that break to
+// CI's merge ref (`catch_up`, joshuafolkken/kit#7058). The push then carries the tree
 // the gate's record describes, so the pre-push hook reuses it rather than re-running the unit suite.
 // Its red is tagged a check, so the stage's infrastructure retry never reads test output as an outage.
 async function gate_merged(): Promise<StepResult | undefined> {
@@ -200,20 +220,57 @@ async function gate_merged(): Promise<StepResult | undefined> {
 	return { ...gate, out, cause: run_ship_stop_cause.CAUSE.CHECK }
 }
 
-// Before the commit stage pushes: a default branch that moved since the sync stage is merged again and
-// the merged tree gated, so the stop lands while the lane still waits on the ship. An unmoved one
-// merges nothing and re-runs no gate; a refusal leaves the merge to the followup, as the sync does.
-// A tree with no green gate record is gated whatever the merge answered: a re-run commit stage finds
-// the merge its red gate stopped on already made, and must not push it without a gate.
-async function catch_up(): Promise<StepResult | undefined> {
+// Whether origin's default branch holds a commit the branch lacks. An unreadable count reads as moved,
+// so the skipped merge is still said on the ship log.
+async function is_behind_default(): Promise<boolean> {
+	try {
+		const default_branch = await git_command.get_default_branch()
+
+		return (await git_command.commit_count_beyond('HEAD', `origin/${default_branch}`)) > 0
+	} catch {
+		return true
+	}
+}
+
+// A default branch that merges into the branch without a conflict is left to CI: the pull request's
+// checks run on the merge ref, the tree combined with the default branch, so a tree only the combined
+// change breaks still turns them red, and the followup merges again (`merge_again`). A probe that
+// cannot tell answers no, keeping the merge and its gate.
+async function is_merge_left_to_ci(): Promise<boolean> {
+	const conflicts = await run_ship_conflict_probe.read_conflicts()
+
+	if (conflicts?.length !== 0) return false
+	if (await is_behind_default()) console.error(LEFT_TO_CI_NOTE)
+
+	return true
+}
+
+// A conflict stops the ship while the lane still waits on it. A refusal leaves the merge to the
+// followup, as the sync does. A tree with no green gate record is gated whatever the merge answered: a
+// re-run commit stage finds the merge its red gate stopped on already made, and must not push it
+// without a gate.
+async function merge_and_gate(is_green: boolean): Promise<StepResult | undefined> {
 	const outcome = await merge_outcome()
 
 	if (outcome.kind === 'conflict') return conflict_result(outcome.files, '')
-	if (outcome.kind !== 'merged' && (await run_ship_scoped.is_gate_green())) return undefined
+	if (is_green && outcome.kind !== 'merged') return undefined
 
 	return await gate_merged()
 }
 
+// Before the commit stage pushes, over a green gate record, a default branch that moved since the sync
+// stage without a conflict is not merged again: the push carries the gated tree, and the merge ref's CI
+// checks the combined one (joshuafolkken/kit#7058, replacing joshuafolkken/kit#4825's local gate —
+// main moves faster than a scoped gate laps, so the ship never caught up). A conflicting move, or one
+// the probe cannot read, is merged and the merged tree gated as before.
+async function catch_up(): Promise<StepResult | undefined> {
+	const is_green = await run_ship_scoped.is_gate_green()
+
+	if (is_green && (await is_merge_left_to_ci())) return undefined
+
+	return await merge_and_gate(is_green)
+}
+
 async function push_merged(title: string): Promise<StepResult | undefined> {
 	const gate = await gate_merged()
 
@@ -239,17 +296,46 @@ function is_checks_failure(failed: JoshResult): boolean {
 	return [failed.out, failed.err].some((text) => names_merge_fixable(text))
 }
 
+// The check code scanning reports as, by name in the followup's `failed checks:` list.
+const CODE_SCANNING_CHECK = 'CodeQL'
+
+// A red the code scanning check itself raised, including one reported beside a merge conflict.
+function names_code_scanning_red(text: string | undefined): boolean {
+	return text?.split(`${FAILURE_REASON_CHECKS}: `)[1]?.includes(CODE_SCANNING_CHECK) === true
+}
+
+// A code scanning alert in the pull request's own files stays red on any base, so a followup red on
+// the code scanning check stops on it, naming each rule and `file:line`, rather than merging and
+// gating again (joshuafolkken/kit#5381). Any other red merges again as before.
+async function own_alerts_stop(failed: JoshResult): Promise<StepResult | undefined> {
+	if ([failed.out, failed.err].every((text) => !names_code_scanning_red(text))) return undefined
+
+	const pr_number = await open_pull_number()
+	const note =
+		pr_number === undefined ? undefined : await git_gh_code_scanning.own_alerts_note(pr_number)
+	if (note === undefined) return undefined
+
+	return { ...failed, out: [failed.out, note].join('\n'), cause: run_ship_stop_cause.CAUSE.CHECK }
+}
+
 // The result to stop on, or `undefined` once a clean merge is pushed and the followup can wait again.
 // A followup that failed on the checks merges again whenever the default branch moved since the push,
 // conflicting or not: a red CI on the merge ref is then reproduced by the local gate or cleared by the
-// new push. An unmoved default branch, or any other failure, stands.
+// new push. An unmoved default branch, an alert in the pull request's own files, or any other failure
+// stands. The merge is said on the ship log (joshuafolkken/kit#6675), so a stop its gate raises reads
+// as the in-ship short path, not as a ship that never caught up.
 async function merge_again(title: string, failed: JoshResult): Promise<StepResult | undefined> {
 	if (!is_checks_failure(failed)) return failed
 
+	const alerts = await own_alerts_stop(failed)
+
+	if (alerts !== undefined) return alerts
+
 	const outcome = await merge_outcome()
 
 	if (outcome.kind === 'conflict') return conflict_result(outcome.files, failed.out)
 	if (outcome.kind !== 'merged') return failed
+	console.error(MERGED_AGAIN_NOTE)
 
 	return await push_merged(title)
 }
@@ -262,7 +348,8 @@ function ignore_wait(): void {
 }
 
 // The wait is marked only while `josh followup` runs: the merge again and its gate run unmarked, so a
-// lane gating here still holds its place (joshuafolkken/kit#4466).
+// lane gating here still holds its place (joshuafolkken/kit#4466). The followup carries the ship
+// marker, so it prints no section of its own (joshuafolkken/kit#5696).
 async function marked_followup(
 	title: string,
 	notify: ReadonlyArray<string>,
@@ -271,7 +358,12 @@ async function marked_followup(
 	mark(true)
 
 	try {
-		return await josh(['followup', title, ...notify])
+		return await josh_command.josh_run(
+			['followup', title, ...notify],
+			should_forward_stderr,
+			undefined,
+			followup_ship_environment.SHIPPED_ENVIRONMENT,
+		)
 	} finally {
 		mark(false)
 	}
@@ -302,8 +394,11 @@ async function followup_stage(
 
 const run_ship_sync = {
 	CONFLICT_NOTE,
+	LEFT_TO_CI_NOTE,
 	MAX_MERGE_RETRIES,
+	MERGED_AGAIN_NOTE,
 	MERGED_GATE_NOTE,
+	PAIR_RED_NOTE,
 	PUSHED_NOTE,
 	PUSH_FAILED_NOTE,
 	catch_up,

package/scripts/run/ship/run-ship-synced-scope.ts

@@ -1,3 +1,5 @@
+import { existsSync } from 'node:fs'
+import path from 'node:path'
 import { gate_labels } from '#scripts/gate/gate-labels'
 import type { GateTree } from '#scripts/gate/gate-tree'
 import type { MovedParts } from '#scripts/gate/moved-paths'
@@ -12,9 +14,11 @@ import { test_read_map, type ReadMap } from '#scripts/test/test-read-map'
 import { related_scope } from '#scripts/test/test-related-scope'
 import { test_related_synced, type SyncedSplit } from '#scripts/test/test-related-synced'
 import { whole_suite_files } from '#scripts/test/whole-suite-files'
+import { run_ship_narrowed } from './run-ship-narrowed'
 
-// **A scoped pair whose records went stale only because a merge with the default branch moved the base
-// re-runs nothing when that merge shares nothing with this branch's change** (joshuafolkken/kit#4985).
+// **A scoped pair after a merge reads unchecked own edits and where the merge meets the branch**
+// (joshuafolkken/kit#4985, joshuafolkken/kit#6279). With no unchecked own edits, it
+// re-runs nothing when that merge shares nothing with this branch's change.
 // The sync, the commit stage's catch-up and a lane's own conflict merge each moved the base under a
 // pair green on the branch side, and the pair re-ran over the branch's related set — minutes of core
 // budget for main's files, which main's CI had already verified.
@@ -28,8 +32,8 @@ import { whole_suite_files } from '#scripts/test/whole-suite-files'
 // gate still runs over the merged tree wherever it ran before (joshuafolkken/kit#4825), and CI runs
 // the whole suite.
 //
-// **Whatever cannot be read settles nothing**: a record that is absent or cannot be compared, a branch
-// side that moved since its record, a merge that changed a check's configuration, or a branch change
+// **Whatever cannot be read settles nothing**: a record that is absent or cannot be compared,
+// a merge that changed a check's configuration, or a branch change
 // git cannot read.
 
 interface SyncedCheck {
@@ -51,31 +55,27 @@ const CHECKS: ReadonlyArray<SyncedCheck> = [
 	},
 ]
 
-function is_sync_only(parts: MovedParts): boolean {
-	return (
-		parts.synced.length > 0 &&
-		parts.changed.every((relative) => run_record_path.is_run_record(relative))
-	)
-}
-
-async function synced_of(
-	check: SyncedCheck,
-	tree: GateTree,
-): Promise<ReadonlyArray<string> | undefined> {
-	const parts = await since_green.read_moved_parts(check.stamp, check.label, undefined, tree)
-
-	return parts !== undefined && is_sync_only(parts) ? parts.synced : undefined
-}
-
-// What the merge brought in, when every stale record moved by nothing else.
-async function synced_files(
+// Each stale record must be comparable; keep own edits from both checks alongside the merge.
+async function moved_files(
 	checks: ReadonlyArray<SyncedCheck>,
 	tree: GateTree,
-): Promise<ReadonlyArray<string> | undefined> {
-	const parts = await Promise.all(checks.map(async (check) => await synced_of(check, tree)))
-	const known = parts.filter((synced) => synced !== undefined)
+): Promise<MovedParts | undefined> {
+	const parts = await Promise.all(
+		checks.map(
+			async (check) =>
+				await since_green.read_moved_parts(check.stamp, check.label, undefined, tree),
+		),
+	)
+	const known = parts.filter((part) => part !== undefined)
 
-	return known.length > 0 && known.length === parts.length ? [...new Set(known.flat())] : undefined
+	if (known.length === 0 || known.length !== parts.length) return undefined
+
+	return {
+		changed: [...new Set(known.flatMap((part) => part.changed))].filter(
+			(file) => !run_record_path.is_run_record(file),
+		),
+		synced: [...new Set(known.flatMap((part) => part.synced))],
+	}
 }
 
 async function branch_change(): Promise<ReadonlyArray<string> | undefined> {
@@ -103,21 +103,102 @@ function has_check(checks: ReadonlyArray<SyncedCheck>, script: string): boolean
 	return checks.some((check) => check.script === script)
 }
 
-// What only one check reads where the two sides meet. `lint:related`'s type-aware rules read every
-// file whose imports reach both, code between included; `test:related` leaves a file the graph
-// cannot split to the branch's own tests (`test-related.ts`), which a settled record would skip.
-function check_overlap(
+// What only `test:related` reads where the two sides meet: it leaves a file the graph cannot split to
+// the branch's own tests (`test-related.ts`), which a settled record would skip.
+function read_by_tests(
 	checks: ReadonlyArray<SyncedCheck>,
 	synced: ReadonlyArray<string>,
-	split: SyncedSplit,
 	map: ReadMap | undefined,
 ): ReadonlyArray<string> {
-	const meeting = has_check(checks, scoped_green.LINT_SCRIPT) ? split.meeting : []
-	const read = has_check(checks, scoped_green.TEST_SCRIPT)
-		? synced.filter((file) => is_read_by_tests(map, file))
-		: []
+	if (!has_check(checks, scoped_green.TEST_SCRIPT)) return []
+
+	return synced.filter((file) => is_read_by_tests(map, file))
+}
+
+// What only `lint:related` reads there: its type-aware rules read every file whose imports reach both,
+// code between included.
+function lint_meeting(
+	checks: ReadonlyArray<SyncedCheck>,
+	split: SyncedSplit,
+): ReadonlyArray<string> {
+	return has_check(checks, scoped_green.LINT_SCRIPT) ? split.meeting : []
+}
+
+// **`test:related` is named over the branch's own change, not over `meeting`** (joshuafolkken/kit#7052):
+// each module there handed to it ran all its importers — 1,536 files where the branch changed 9. Its
+// run over the branch's change reaches every `shared` test, capped as the branch's own run is; CI runs
+// the whole suite. A file the branch deleted is no longer one to name.
+function test_overlap_of(
+	root: string,
+	branch: ReadonlyArray<string>,
+	split: SyncedSplit,
+	common: ReadonlyArray<string>,
+): ReadonlyArray<string> {
+	const own =
+		split.shared.length > 0 ? branch.filter((file) => existsSync(path.join(root, file))) : []
+
+	return [...new Set([...common, ...own])]
+}
 
-	return [...meeting, ...read]
+// What a merge-only staleness reads: the stale checks, what the merge brought in, and where it meets
+// this branch's change — the files the pair is narrowed to (`run-ship-narrowed.ts`) when any. An
+// `overlap` of `undefined` is a merge the import graph could not split, `unsplit` the graph's failure
+// (`test-related-synced.ts`), which the ship logs in `unsplit_line` and records on its lap
+// (joshuafolkken/kit#6196): the pair runs as before rather than naming every synced module
+// (joshuafolkken/kit#6185).
+interface SyncReading {
+	checks: ReadonlyArray<SyncedCheck>
+	synced: ReadonlyArray<string>
+	overlap: ReadonlyArray<string> | undefined
+	// The part of `overlap` `test:related` is named over, plus the branch's change where a test meets
+	// it (`test_overlap_of`); absent, the check reads `overlap`.
+	test_overlap?: ReadonlyArray<string>
+	unsplit?: string
+}
+
+type Overlap = Pick<SyncReading, 'overlap' | 'test_overlap' | 'unsplit'>
+
+function joined(
+	first: ReadonlyArray<string>,
+	second: ReadonlyArray<string>,
+): ReadonlyArray<string> {
+	return [...new Set([...first, ...second])]
+}
+
+function with_own_edits(overlap: Overlap, changed: ReadonlyArray<string>): Overlap {
+	if (overlap.overlap === undefined) return overlap
+
+	return {
+		...overlap,
+		overlap: joined(changed, overlap.overlap),
+		test_overlap: joined(changed, overlap.test_overlap ?? []),
+	}
+}
+
+// Every file a named pair runs over, for the check that each is still nameable.
+function named_of(reading: SyncReading): ReadonlyArray<string> | undefined {
+	if (reading.overlap === undefined) return undefined
+
+	return joined(reading.overlap, reading.test_overlap ?? [])
+}
+
+// The files one check of a named pair runs over: its own part of the reading where it has one —
+// `test:related` its `test_overlap`, `lint:related` the `overlap` alone.
+function files_for(
+	reading: SyncReading | undefined,
+	script: string,
+	files: ReadonlyArray<string>,
+): ReadonlyArray<string> {
+	const own = script === scoped_green.TEST_SCRIPT ? reading?.test_overlap : reading?.overlap
+
+	return own ?? files
+}
+
+function unsplit_line(failure: string): string {
+	return (
+		'scoped pair: the import graph could not split the merge with the default branch ' +
+		`(${failure}), so the pair runs as before.`
+	)
 }
 
 // The synced files and tests where the merge and this branch's change meet.
@@ -125,7 +206,7 @@ async function overlap_of(
 	checks: ReadonlyArray<SyncedCheck>,
 	synced: ReadonlyArray<string>,
 	branch: ReadonlyArray<string>,
-): Promise<ReadonlyArray<string>> {
+): Promise<Overlap> {
 	const root = await changed_file_scope.repository_root_or_cwd()
 	const map = test_read_map.read_map(root)
 	const split = await test_related_synced.split(root, synced, branch, map)
@@ -136,43 +217,66 @@ async function overlap_of(
 			related_scope.is_relatable(file) && !branch.includes(file) && !split.left.includes(file),
 	)
 
-	return [...both, ...split.shared, ...unsplit, ...check_overlap(checks, synced, split, map)]
+	if (split.failure !== undefined && unsplit.length > 0) {
+		return { overlap: undefined, unsplit: split.failure }
+	}
+
+	const common = [...both, ...unsplit, ...read_by_tests(checks, synced, map)]
+	// `shared` is the tests within `meeting`: a file both name counts once (joshuafolkken/kit#6197).
+	const named = [...common, ...split.shared, ...lint_meeting(checks, split)]
+
+	return {
+		overlap: [...new Set(named)],
+		test_overlap: test_overlap_of(root, branch, split, common),
+	}
 }
 
-async function unshared_sync(
-	checks: ReadonlyArray<SyncedCheck>,
+function checks_of(scripts: ReadonlyArray<string>): ReadonlyArray<SyncedCheck> {
+	return CHECKS.filter((check) => scripts.includes(check.script))
+}
+
+// Unknown records or an absent merge keep the pair's existing fallback.
+async function read_sync(
 	tree: GateTree,
-): Promise<ReadonlyArray<string> | undefined> {
-	const synced = await synced_files(checks, tree)
-	const branch = synced === undefined ? undefined : await branch_change()
+	scripts: ReadonlyArray<string>,
+): Promise<SyncReading | undefined> {
+	const checks = checks_of(scripts)
+	const parts = await moved_files(checks, tree)
+
+	if (parts === undefined || parts.synced.length === 0) return undefined
 
-	if (synced === undefined || branch === undefined) return undefined
+	const branch = await branch_change()
 
-	const overlap = await overlap_of(checks, synced, branch)
+	if (branch === undefined) return undefined
 
-	return overlap.length === 0 ? synced : undefined
+	const overlap = await overlap_of(checks, parts.synced, branch)
+
+	return {
+		checks,
+		synced: parts.synced,
+		...with_own_edits(overlap, parts.changed),
+	}
 }
 
-function reason(scripts: ReadonlyArray<string>, synced: ReadonlyArray<string>): string {
+function reason(checks: ReadonlyArray<SyncedCheck>, synced: ReadonlyArray<string>): string {
 	return (
-		`scoped pair: ${scripts.join(' and ')} not re-run — the ${String(synced.length)} file(s) ` +
-		"the merge with the default branch brought in share no file or test with this branch's change."
+		`scoped pair: ${checks.map((check) => check.script).join(' and ')} not re-run — the ` +
+		`${String(synced.length)} file(s) the merge with the default branch brought in share no file ` +
+		"or test with this branch's change."
 	)
 }
 
 // The line a settled pair prints, after re-recording each stale check green on this tree so the gate
-// and the brief read it as checked — or `undefined`, and the pair runs as before.
-async function settle(tree: GateTree, scripts: ReadonlyArray<string>): Promise<string | undefined> {
-	const checks = CHECKS.filter((check) => scripts.includes(check.script))
-	const synced = await unshared_sync(checks, tree)
-
-	if (synced === undefined) return undefined
+// and the brief read it as checked — or `undefined` where the merge meets the branch.
+function settle(reading: SyncReading, tree: GateTree): string | undefined {
+	if (reading.overlap === undefined || reading.overlap.length > 0) return undefined
 
-	for (const check of checks) scoped_green.record_green(check.stamp, tree)
+	run_ship_narrowed.record(reading.checks, tree)
 
-	return reason(scripts, synced)
+	return reason(reading.checks, reading.synced)
 }
 
-const run_ship_synced_scope = { settle }
+const run_ship_synced_scope = { checks_of, files_for, named_of, read_sync, settle, unsplit_line }
 
+export type { SyncedCheck, SyncReading }
 export { run_ship_synced_scope }

package/scripts/run/ship/run-ship-tree-stamp.ts

@@ -0,0 +1,35 @@
+import type { GateTree } from '#scripts/gate/gate-tree'
+import {
+	file_map_stamp,
+	type FileMapStamp,
+	type FileMapStampAccess,
+} from '#scripts/josh/file-map-stamp'
+
+// One ship stage's record of the tree it passed on: a re-entry on exactly that tree, base and inputs
+// reuses the pass, and any move runs the stage again (joshuafolkken/kit#6986).
+
+function matches(prior: FileMapStamp | undefined, tree: GateTree): boolean {
+	if (prior?.completed_at === undefined || Object.keys(tree.files).length === 0) return false
+
+	return (
+		file_map_stamp.describes_base(prior, tree.base) &&
+		file_map_stamp.changed_since(prior, tree.files).length === 0
+	)
+}
+
+function is_reusable(stamp: FileMapStampAccess, tree: GateTree): boolean {
+	const prior = stamp.read()
+
+	return prior !== undefined && stamp.describes_inputs(prior) && matches(prior, tree)
+}
+
+// The tree read before the stage ran, so an edit made during it is never blessed.
+function complete(stamp: FileMapStampAccess, tree: GateTree, code: number): void {
+	if (code !== 0) return
+	stamp.write(tree.files, undefined, tree.base)
+	stamp.complete()
+}
+
+const run_ship_tree_stamp = { complete, is_reusable }
+
+export { run_ship_tree_stamp }

package/scripts/run/ship/run-ship-wait-cli.ts

@@ -1,7 +1,6 @@
-#!/usr/bin/env tsx
 import { setTimeout as sleep } from 'node:timers/promises'
-import { fileURLToPath } from 'node:url'
 import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { poll } from '#scripts/lib/poll'
 import { run_ship_detach } from './run-ship-detach'
 import { run_ship_probe } from './run-ship-probe'
 import { run_ship_stage } from './run-ship-stage'
@@ -17,9 +16,8 @@ import { run_ship_waiter } from './run-ship-waiter'
 // - `pending` — the chunk ran out with the ship still before its commit: issue the wait again.
 //
 // **A chunk ends below the five-minute prompt-cache TTL a lane child runs on** (`lane-child-marker.ts`),
-// so re-issuing it is the keep-alive: the next request reads the cached context back (66k tokens on
-// Opus 5.5, about $0.013) instead of writing it whole again after the wait (about $0.33) —
-// joshuafolkken/kit#5344. The heartbeat outlives the chunk by the session gap.
+// so re-issuing it keeps the next request on cached context instead of rewriting the whole context
+// (joshuafolkken/kit#5344). The heartbeat outlives the chunk by the session gap.
 
 const VERDICT = {
 	RETURNED: 'returned',
@@ -37,14 +35,13 @@ interface Waited {
 
 const CHUNK_MS = 270_000
 const POLL_MS = 2000
-const ARGV_OFFSET = 2
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const USAGE = 'Usage: josh ship:wait <N>'
 const NO_REPOSITORY_NOTE = 'not inside a git repository'
 
-const { COMMIT, ROUND_TWO, FOLLOWUP, REPORT } = run_ship_stage.STAGE
-const PAST_COMMIT: ReadonlySet<string> = new Set([ROUND_TWO, FOLLOWUP, REPORT])
+const { COMMIT, FOLLOWUP, REPORT } = run_ship_stage.STAGE
+const PAST_COMMIT: ReadonlySet<string> = new Set([FOLLOWUP, REPORT])
 
 // Past the commit in the current attempt: the record's `done` outlives a stop after the commit, so a
 // re-ship after a followup stop would read as committed before its own gate and review ran. `started`
@@ -76,29 +73,34 @@ function settled(repository: string, issue: string): Waited | undefined {
 	return ended(repository, issue)
 }
 
-async function poll(repository: string, issue: string, deadline: number): Promise<Waited> {
-	while (Date.now() < deadline) {
-		run_ship_waiter.beat(repository, issue)
-		const waited = settled(repository, issue)
+async function wait_within(repository: string, issue: string, deadline: number): Promise<Waited> {
+	return await poll.wait_for(
+		() => {
+			if (Date.now() >= deadline) return { verdict: VERDICT.PENDING }
+			run_ship_waiter.beat(repository, issue)
 
-		if (waited !== undefined) return waited
-
-		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the supervisor's progress
-		await sleep(POLL_MS)
-	}
-
-	return { verdict: VERDICT.PENDING }
+			return settled(repository, issue)
+		},
+		{ interval_ms: POLL_MS, sleeper: sleep },
+	)
 }
 
 // A `pending` chunk keeps the heartbeat for the next one; any other verdict ends the wait for good.
 async function wait_for(repository: string, issue: string, chunk_ms = CHUNK_MS): Promise<Waited> {
-	const waited = await poll(repository, issue, Date.now() + chunk_ms)
+	const waited = await wait_within(repository, issue, Date.now() + chunk_ms)
 
 	if (waited.verdict !== VERDICT.PENDING) run_ship_waiter.leave(repository, issue)
 
 	return waited
 }
 
+// The chunk counts from the process start, not the wait's: both clocks it is sized against start at the
+// session's call, and a `ship --detach` reaches the wait only after its preflight (joshuafolkken/kit#5625).
+// None left reads `pending` at once, so the re-issue gets fresh clocks.
+function chunk_left(): number {
+	return CHUNK_MS - performance.now()
+}
+
 // Each verdict carries what the session does next, so the instruction lives with the command.
 function next_action(issue: string): Record<Verdict, string> {
 	return {
@@ -131,15 +133,11 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 		return FAILURE_EXIT_CODE
 	}
 
-	report(issue, await wait_for(repository, issue))
+	report(issue, await wait_for(repository, issue, chunk_left()))
 
 	return SUCCESS_EXIT_CODE
 }
 
 const run_ship_wait_cli = { CHUNK_MS, VERDICT, run, wait_for }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-	process.exitCode = await run(process.argv.slice(ARGV_OFFSET))
-}
-
 export { run_ship_wait_cli }