@joshuafolkken/kit 1.1784.0 → 1.2114.0

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

@@ -1,22 +1,31 @@
 import { git_gh_pr_read } from '#scripts/gh/git-gh-pr-read'
-import { is_merge_conflict } from '#scripts/gh/git-pr-checks-eval'
+import {
+	FAILURE_MESSAGE_PREFIX,
+	FAILURE_REASON_CHECKS,
+	FAILURE_REASON_CONFLICT,
+} from '#scripts/gh/git-pr-checks-eval'
 import { git_command } from '#scripts/git/git-command'
 import { main_merge, type MergeOutcome } from '#scripts/git/main-merge'
+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_lap } from './run-ship-lap'
 import { run_ship_overlap } from './run-ship-overlap'
 import { run_ship_scoped } from './run-ship-scoped'
-import type { Cause } from './run-ship-stop-cause'
+import { run_ship_stop_cause, type Cause } from './run-ship-stop-cause'
 
 // `josh ship` keeps the branch current with the default branch itself: a default branch that moves
 // while the pull request opens and CI runs would otherwise stop the followup as `interrupted`, though
 // merging the default branch again usually resolves it.
 //
-// So the merge happens mechanically: once before the commit (`sync_stage`), and once when
-// the followup fails on a pull request GitHub reports `DIRTY` (`followup_stage`). A conflict only on
-// generated files is regenerated by the merge itself (`main-merge-regenerate.ts`); any other conflict
+// 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
+// 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.
 
+const { STEP, timed } = run_ship_lap
 const should_forward_stderr = true
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
@@ -27,19 +36,32 @@ const CONFLICT_NOTE = 'merging the default branch left unmerged paths:'
 const DEFERRED_PREFIX = 'merge deferred to the followup: '
 const CURRENT_SUFFIX = ' brings nothing in'
 const MERGED_PREFIX = 'merged '
+const MERGED_GATE_NOTE =
+	'the default branch moved since the sync; the tree merged with it fails the gate:'
+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:'
 
 // 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
 // that reused a green record — so its few seconds are not timed as a run of it. `preconditions` names
 // the kinds of the preconditions a stopped preflight found unmet (`run-ship-preflight.ts`). `cause` is the
-// one a stopped review round tagged its stop with (`run-ship-stop-cause.ts`).
+// one a stopped stage tagged its stop with — a review round, or a red gate over a merged tree
+// (`run-ship-stop-cause.ts`). `reason` says why the stage ran or was skipped, written on its event line
+// (`run-ship-review-reason.ts`).
 interface StepResult extends JoshResult {
 	is_skipped?: boolean
+	reason?: string
 	conflicts?: ReadonlyArray<string>
 	preconditions?: ReadonlyArray<string>
 	cause?: Cause
 }
 
+// The push of a tree already committed, with no pull request touched.
+function push_argv(title: string): ReadonlyArray<string> {
+	return ['git', '-y', '--skip-commit', '--skip-pr', title]
+}
+
 async function josh(argv: ReadonlyArray<string>): Promise<JoshResult> {
 	return await josh_command.josh_run(argv, should_forward_stderr)
 }
@@ -48,7 +70,7 @@ async function josh(argv: ReadonlyArray<string>): Promise<JoshResult> {
 // changed, and the followup still finds a real conflict on GitHub's side.
 async function merge_outcome(): Promise<MergeOutcome> {
 	try {
-		return await main_merge.merge()
+		return await timed(STEP.MERGE, async () => await main_merge.merge())
 	} catch (error) {
 		return { kind: 'refused', message: error_text.message_of(error) }
 	}
@@ -68,51 +90,161 @@ function sync_note(outcome: Exclude<MergeOutcome, { kind: 'conflict' }>): string
 		: `${MERGED_PREFIX}${outcome.branch}`
 }
 
-// A refusal does not stop the commit: the guard refuses only uncommitted work the default branch also
-// touches, and once that work is committed the followup merges again on a clean tree. A merge that changed
-// the tree is checked by the gate stage that follows, so the commit never carries
-// an unchecked merge and the gate's record names the merge base the push carries.
-//
+// Uncommitted work is committed locally first, never stashed: the merge guard refuses uncommitted work
+// the default branch also touches, and a merge deferred past it met its conflict only after the gate,
+// both review rounds and CI (joshuafolkken/kit#4708). The commit is not pushed here: a tree the sync
+// leaves unmerged goes out at the commit stage once the gate is green (`push_ahead` pushes a merged
+// one). A refusal left — a fetch that failed — does not stop the ship: the commit stage and the
+// followup merge again.
+// The pre-commit prettier, cspell and eslint are switched off for it: the gate or the scoped pair runs
+// the same checks over this tree before anything is pushed, and the hooks only waited for the core
+// budget to repeat them (joshuafolkken/kit#4985).
+async function commit_locally(title: string, is_dirty: boolean): Promise<JoshResult | undefined> {
+	if (!is_dirty) return undefined
+
+	const commit = await timed(
+		STEP.LOCAL_COMMIT,
+		async () =>
+			await josh_command.josh_run(
+				['git', '-y', '--skip-push', '--skip-pr', title],
+				should_forward_stderr,
+				undefined,
+				{ [pre_commit_lint_switch.SWITCH_ENV_KEY]: 'off' },
+			),
+	)
+
+	return commit.code === SUCCESS_EXIT_CODE ? undefined : commit
+}
+
+// **A merge the sync made is pushed at once onto an open pull request, ahead of the gate**
+// (joshuafolkken/kit#5067): CI and SonarQube start from this push, and pushed after the gate they ran
+// behind it, leaving the followup minutes of waiting. Only the pull request's own branch moves; the
+// merge still needs the gate, the review attest and a green CI, and a red gate stops the ship before
+// the followup as before, the next push replacing the commit. Its pre-push hook runs the related tests
+// (`pre-push-related-switch.ts`), since the gate over this same tree runs the whole suite next. A
+// branch with no open pull request pushes nothing here: CI runs on pull requests only. An unmoved
+// 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.
+async function push_ahead(title: string): Promise<string> {
+	const push = await timed(
+		STEP.PUSH,
+		async () =>
+			await josh_command.josh_run(push_argv(title), should_forward_stderr, undefined, {
+				[pre_push_related_switch.SWITCH_ENV_KEY]: pre_push_related_switch.SWITCH_ON,
+			}),
+	)
+
+	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> {
+	try {
+		return (await git_gh_pr_read.pr_get_number(await git_command.branch())) !== undefined
+	} catch {
+		return false
+	}
+}
+
+async function pushed_note(outcome: MergeOutcome, title: string): Promise<string> {
+	if (outcome.kind !== 'merged' || !(await has_open_pull())) return ''
+
+	return await push_ahead(title)
+}
+
+async function waited_note(issue: string): Promise<string> {
+	const overlap = await timed(
+		STEP.OVERLAP_WAIT,
+		async () => await run_ship_overlap.await_overlap(issue),
+	)
+
+	return run_ship_overlap.note(overlap)
+}
+
 // The merge waits first for any lane whose open pull request changes the same paths
 // (`run-ship-overlap.ts`), so it brings that pull request in before the gate rather than meeting it
 // as `DIRTY` after CI.
-async function sync_stage(issue: string): Promise<StepResult> {
-	const waited = run_ship_overlap.note(await run_ship_overlap.await_overlap(issue))
+async function sync_stage(issue: string, title: string, is_dirty: boolean): Promise<StepResult> {
+	const waited = await waited_note(issue)
+	const failed_commit = await commit_locally(title, is_dirty)
+
+	if (failed_commit !== undefined) {
+		const out = [waited, failed_commit.out].filter((line) => line !== '').join('\n')
+
+		return { ...failed_commit, out }
+	}
+
 	const outcome = await merge_outcome()
 
 	if (outcome.kind === 'conflict') return conflict_result(outcome.files, waited)
 
-	const out = [waited, sync_note(outcome)].filter((line) => line !== '').join('\n')
+	const pushed = await pushed_note(outcome, title)
+	const out = [waited, sync_note(outcome), pushed].filter((line) => line !== '').join('\n')
 
 	return { code: SUCCESS_EXIT_CODE, out }
 }
 
-// Any read that fails answers "not conflicting": the followup failure then stands as it was.
-async function is_conflicting(): Promise<boolean> {
-	try {
-		const state = await git_gh_pr_read.pr_get_merge_state(await git_command.branch())
+// 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
+// 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> {
+	const gate = await run_ship_scoped.scoped_gate()
 
-		return is_merge_conflict(state?.merge_state_status)
-	} catch {
-		return false
-	}
+	if (gate.code === SUCCESS_EXIT_CODE) return undefined
+
+	const out = [MERGED_GATE_NOTE, gate.out].filter((line) => line !== '').join('\n')
+
+	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> {
+	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
+
+	return await gate_merged()
 }
 
-// The merged tree is gated before it is pushed: 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.
 async function push_merged(title: string): Promise<StepResult | undefined> {
-	const gate = await run_ship_scoped.scoped_gate()
+	const gate = await gate_merged()
 
-	if (gate.code !== SUCCESS_EXIT_CODE) return gate
+	if (gate !== undefined) return gate
 
-	const push = await josh(['git', '-y', '--skip-commit', '--skip-pr', title])
+	const push = await josh(push_argv(title))
 
 	return push.code === SUCCESS_EXIT_CODE ? undefined : push
 }
 
+// The followup's reasons a newer base can change: a red check or a conflict.
+const MERGE_FIXABLE_REASONS = [FAILURE_REASON_CHECKS, FAILURE_REASON_CONFLICT]
+
+function names_merge_fixable(text: string | undefined): boolean {
+	if (text?.includes(FAILURE_MESSAGE_PREFIX) !== true) return false
+
+	return MERGE_FIXABLE_REASONS.some((reason) => text.includes(reason))
+}
+
+// Whether the followup failed on the pull request's checks — a red check or a conflict. A refusal
+// before the wait, or a review blocker alone, is not one: its text carries neither reason.
+function is_checks_failure(failed: JoshResult): boolean {
+	return [failed.out, failed.err].some((text) => names_merge_fixable(text))
+}
+
 // 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.
 async function merge_again(title: string, failed: JoshResult): Promise<StepResult | undefined> {
-	if (!(await is_conflicting())) return failed
+	if (!is_checks_failure(failed)) return failed
 
 	const outcome = await merge_outcome()
 
@@ -168,7 +300,16 @@ async function followup_stage(
 	return await followup_attempt(title, notify, mark, 0)
 }
 
-const run_ship_sync = { CONFLICT_NOTE, MAX_MERGE_RETRIES, followup_stage, sync_stage }
+const run_ship_sync = {
+	CONFLICT_NOTE,
+	MAX_MERGE_RETRIES,
+	MERGED_GATE_NOTE,
+	PUSHED_NOTE,
+	PUSH_FAILED_NOTE,
+	catch_up,
+	followup_stage,
+	sync_stage,
+}
 
 export type { StepResult, WaitMark }
 export { run_ship_sync }

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

@@ -0,0 +1,178 @@
+import { gate_labels } from '#scripts/gate/gate-labels'
+import type { GateTree } from '#scripts/gate/gate-tree'
+import type { MovedParts } from '#scripts/gate/moved-paths'
+import { scoped_green } from '#scripts/gate/scoped-green'
+import { since_green } from '#scripts/gate/since-green'
+import { changed_file_scope } from '#scripts/git/changed-file-scope'
+import { changed_paths } from '#scripts/git/changed-paths'
+import type { FileMapStampAccess } from '#scripts/josh/file-map-stamp'
+import { run_record_path } from '#scripts/josh/run-record-path'
+import { review_stamps } from '#scripts/review/review-stamps'
+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'
+
+// **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).
+// 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.
+//
+// **Where the two can meet still runs.** A file both sides changed, a test reaching both a synced module
+// and this branch's change (`test-related-synced.ts`), or a synced module the import graph cannot
+// split keeps the pair running as before, narrowed by the checks themselves (`since-green.ts`). So
+// does, for `lint:related`, any file whose imports reach both sides, and for `test:related` a synced
+// file every test depends on or a non-code file a test reads: `josh test:related` leaves those to the
+// branch's own tests, which a settled record would skip. The
+// 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
+// git cannot read.
+
+interface SyncedCheck {
+	script: string
+	label: string
+	stamp: FileMapStampAccess
+}
+
+const CHECKS: ReadonlyArray<SyncedCheck> = [
+	{
+		script: scoped_green.LINT_SCRIPT,
+		label: gate_labels.LINT_LABEL,
+		stamp: review_stamps.lint_related_stamp,
+	},
+	{
+		script: scoped_green.TEST_SCRIPT,
+		label: gate_labels.UNIT_LABEL,
+		stamp: review_stamps.test_related_stamp,
+	},
+]
+
+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(
+	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)
+
+	return known.length > 0 && known.length === parts.length ? [...new Set(known.flat())] : undefined
+}
+
+async function branch_change(): Promise<ReadonlyArray<string> | undefined> {
+	try {
+		return await changed_paths.read_changed_paths(false)
+	} catch {
+		return undefined
+	}
+}
+
+function is_whole_suite(file: string): boolean {
+	return whole_suite_files.WHOLE_SUITE_FILES.has(file)
+}
+
+// A synced file a test can reach with no import the graph splits: one every test depends on, or a
+// non-code file a recorded test reads — every one of them when no map was recorded.
+function is_read_by_tests(map: ReadMap | undefined, file: string): boolean {
+	if (is_whole_suite(file)) return true
+	if (related_scope.is_relatable(file)) return false
+
+	return map === undefined || test_read_map.readers_of(map, file).length > 0
+}
+
+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(
+	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))
+		: []
+
+	return [...meeting, ...read]
+}
+
+// The synced files and tests where the merge and this branch's change meet.
+async function overlap_of(
+	checks: ReadonlyArray<SyncedCheck>,
+	synced: ReadonlyArray<string>,
+	branch: ReadonlyArray<string>,
+): Promise<ReadonlyArray<string>> {
+	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)
+	const both = synced.filter((file) => branch.includes(file))
+	// Code the graph left unsplit — whole-suite modules included, which it never splits.
+	const unsplit = synced.filter(
+		(file) =>
+			related_scope.is_relatable(file) && !branch.includes(file) && !split.left.includes(file),
+	)
+
+	return [...both, ...split.shared, ...unsplit, ...check_overlap(checks, synced, split, map)]
+}
+
+async function unshared_sync(
+	checks: ReadonlyArray<SyncedCheck>,
+	tree: GateTree,
+): Promise<ReadonlyArray<string> | undefined> {
+	const synced = await synced_files(checks, tree)
+	const branch = synced === undefined ? undefined : await branch_change()
+
+	if (synced === undefined || branch === undefined) return undefined
+
+	const overlap = await overlap_of(checks, synced, branch)
+
+	return overlap.length === 0 ? synced : undefined
+}
+
+function reason(scripts: ReadonlyArray<string>, 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."
+	)
+}
+
+// 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
+
+	for (const check of checks) scoped_green.record_green(check.stamp, tree)
+
+	return reason(scripts, synced)
+}
+
+const run_ship_synced_scope = { settle }
+
+export { run_ship_synced_scope }

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

@@ -0,0 +1,145 @@
+#!/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 { run_ship_detach } from './run-ship-detach'
+import { run_ship_probe } from './run-ship-probe'
+import { run_ship_stage } from './run-ship-stage'
+import { run_ship_waiter } from './run-ship-waiter'
+
+// `josh ship:wait <N>` — the lane session that detached a ship waits here for the gate and review
+// round 1, so a stop there comes back to it (`run-ship-waiter.ts`) rather than to a fresh session
+// (joshuafolkken/kit#4711). One verdict line, then the stop note on `returned`:
+//
+// - `returned` — the supervisor stopped and handed its note to this session: fix it and ship again.
+// - `passed` — the ship committed, or finished: what follows is the supervisor's alone.
+// - `ended` — the supervisor ended with no note for this session: nothing is left to wait for.
+// - `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.
+
+const VERDICT = {
+	RETURNED: 'returned',
+	PASSED: 'passed',
+	ENDED: 'ended',
+	PENDING: 'pending',
+} as const
+
+type Verdict = (typeof VERDICT)[keyof typeof VERDICT]
+
+interface Waited {
+	verdict: Verdict
+	note?: string
+}
+
+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])
+
+// 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`
+// is cleared at every stop, so it says what this attempt reached.
+function is_committed(repository: string, issue: string): boolean {
+	const target = run_ship_stage.record_path(repository, issue)
+	const started = run_ship_stage.read_started(target)
+
+	if (started.some((stage) => PAST_COMMIT.has(stage))) return true
+
+	return started.includes(COMMIT) && run_ship_stage.read_done(target).has(COMMIT)
+}
+
+// The supervisor's own end, where it left no note: `undefined` while it still runs.
+function ended(repository: string, issue: string): Waited | undefined {
+	const result = run_ship_detach.read_result(repository, issue)?.result
+
+	if (result === 'running') return undefined
+
+	return { verdict: result === 'success' ? VERDICT.PASSED : VERDICT.ENDED }
+}
+
+function settled(repository: string, issue: string): Waited | undefined {
+	const note = run_ship_waiter.take(repository, issue)
+
+	if (note !== undefined) return { verdict: VERDICT.RETURNED, note }
+	if (is_committed(repository, issue)) return { verdict: VERDICT.PASSED }
+
+	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)
+
+		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 }
+}
+
+// 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)
+
+	if (waited.verdict !== VERDICT.PENDING) run_ship_waiter.leave(repository, issue)
+
+	return waited
+}
+
+// Each verdict carries what the session does next, so the instruction lives with the command.
+function next_action(issue: string): Record<Verdict, string> {
+	return {
+		[VERDICT.RETURNED]: 'the ship stopped: fix what the note below says, then ship again',
+		[VERDICT.PASSED]: 'the supervisor ships the rest: end the turn',
+		[VERDICT.ENDED]: 'nothing is left to wait for: end the turn',
+		[VERDICT.PENDING]: `still before the commit: on \`pnpm josh cost --cut\` \`under\`, run \`pnpm josh ship:wait ${issue}\` again; else end the turn`,
+	}
+}
+
+function report(issue: string, waited: Waited): void {
+	console.info(`${waited.verdict} — ${next_action(issue)[waited.verdict]}`)
+	if (waited.note !== undefined) console.info(waited.note)
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const issue = issue_number_shape.single_of(argv)
+
+	if (issue === undefined) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const repository = await run_ship_probe.repository_directory()
+
+	if (repository === undefined) {
+		console.error(NO_REPOSITORY_NOTE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	report(issue, await wait_for(repository, issue))
+
+	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 }