@joshuafolkken/kit 1.1784.0 → 1.2116.0

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

@@ -1,16 +1,24 @@
-import { git_gh_issue_write } from '#scripts/gh/git-gh-issue-write'
 import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { lane_child_marker } from '#scripts/lane/lane-child-marker'
 import { cli_flags } from '#scripts/lib/cli-flags'
 import { observation_ledger_home } from '#scripts/observations/observation-ledger-home'
-import { review_comment_round } from './review-comment-round'
+import type { StopFinding } from '#scripts/run/ship/run-ship-review'
+import { review_comment_carry } from './review-comment-carry'
 import { review_finding_ledger, type Finding, type LineKind } from './review-finding-ledger'
+import { review_finding_text } from './review-finding-text'
 import { review_interaction } from './review-interaction'
+import { review_lane_handover } from './review-lane-handover'
 import { review_record, type RecordVerdict } from './review-record'
+import { review_record_code_round } from './review-record-code-round'
+import { review_record_comment } from './review-record-comment'
+import { review_record_interaction } from './review-record-interaction'
+import type { ReuseAnswer } from './review-round-reuse'
+import { review_stop_log } from './review-stop-log'
 
 // `josh review:record --issue <N> [<category>:<severity>:<file> ...]` — the one write path for a
-// `/code-review` round's findings. It appends a `- rf:` line per finding to
+// `/code-review` round's findings. It appends a `- rb:` round boundary and a `- rf:` line per finding to
 // the issue's own file of the observation ledger, which the run's commit carries like any other
-// ledger change. **A call with no findings is a zero-finding round, and it still writes one line** — so the
+// ledger change. **A call with no findings is a zero-finding round, and it still writes one `- rf:` line** — so the
 // round that found nothing is recorded rather than mistaken for a round nobody reviewed.
 //
 // **`--comment` records a round that ran after the pull request opened**: the same lines go to the
@@ -21,26 +29,50 @@ import { review_record, type RecordVerdict } from './review-record'
 //
 // `josh review:record --check --issue <N>` is the read half `pnpm josh followup` runs before it
 // merges: `ok` / `not-required` exit zero, `missing` exits non-zero so the
-// merge is refused until the round is recorded. It mirrors `josh review:attest --check`.
+// merge is refused until the round is recorded. It mirrors `josh review:attest --check`. A recorded
+// code round adds whether the ship reuses it (`review-round-reuse.ts`); the exit code does not change.
 //
 // **`--interaction` records and checks the interaction review's pass instead** (`review-interaction.ts`):
 // the same grammar under `- ri:`. It takes no `--comment` — the pass runs before the pull request, and
 // a pass kept only on the issue would leave the merge gate reading it as missing.
+//
+// **A finding written with its reason — `<spec> — <sentence>` — also lands in the durable stop log**,
+// marked fixed (joshuafolkken/kit#4817). The ledger keeps the spec alone, as it always has; the stop
+// log is the one record that keeps a finding's location and reason, so a lane's own round reaches the
+// next stop's fix and the next review (`review-prior-findings.ts`) the way a ship's round already does.
 
 const FAILURE_EXIT_CODE = 1
 const USAGE =
-	'Usage: josh review:record --issue <N> [--comment | --interaction] [<category>:<severity>:<file> ...] | josh review:record --check [--interaction] --issue <N>'
+	'Usage: josh review:record --issue <N> [--comment | --interaction] [[<disposition> ]<category>:<severity>:<file>[ — <reason>] ...] | josh review:record --check [--interaction] --issue <N>'
 const FILE_HINT = '  <file>: the cited path, optionally with :line'
+const DISPOSITION_HINT =
+	'  <disposition>: optional — fixed | false-positive | filed:#<M> | deferred:#<M>; josh review:round2 skips only when every High/Medium is fixed or false-positive'
+const REASON_HINT =
+	'  <reason>: optional, one sentence on what was wrong, kept for the lane’s next review and fix — pass each finding with its reason as one single-quoted argument'
+const RECORD_STAGE = 'review:record'
 const CHECK_USAGE = 'Usage: josh review:record --check [--interaction] --issue <N>'
 const RECORDED_LINE = 'Recorded: the review round for this issue is in the ledger.'
+const REUSED_LINE =
+	'Reused: josh ship takes this round as its round 1 — the files this round covers hold still since the record. A default branch the ship’s sync merges in moves them only where it changed a file this round covers, and the ship then reviews round 1 again itself.'
+const DELTA_LINE =
+	'Reused, delta to round 2: josh ship takes this round as its round 1 and does not review it again — every file moved since the record is one round 2 reads after the commit, or the ship’s own round 1 stopped on it.'
+
+// The condition that re-runs round 1, and the path that met it, named rather than listed among every
+// condition that could (joshuafolkken/kit#4941).
+function review_again_line(cause = 'the reuse question gave no reason'): string {
+	return `Not reused: josh ship reviews round 1 again — ${cause}. Run \`pnpm josh run:review\` and the round-1 \`/code-review\` here (chain-rule.md step 0).`
+}
+
+function reuse_line(answer: ReuseAnswer): string {
+	if (answer.reuse === 'again') return review_again_line(answer.cause)
+
+	return answer.reuse === 'delta' ? DELTA_LINE : REUSED_LINE
+}
+
 const NOT_REQUIRED_LINE =
 	'No review-finding ledger is kept in this checkout, so there is nothing to check.'
-const INTERACTION_NOT_REQUIRED_LINE =
-	'No interaction review is due: the change touches no run tooling, or this checkout keeps no ledger.'
-const CARRIED_LINE =
-	'review-finding line(s) recorded on closed issues after their pull requests opened into the ledger.'
-const CARRY_FAILED_LINE =
-	'Could not carry the closed issues’ comment rounds into the ledger; the next round retries:'
+const LANE_CARRY_LINE =
+	'Not carrying the closed issues’ comment rounds: a lane child leaves them to `pnpm josh observations:flush`.'
 const OPTIONS = {
 	issue: { type: 'string' },
 	check: { type: 'boolean' },
@@ -83,15 +115,31 @@ function parse_finding(spec: string): Finding | undefined {
 	return to_finding(spec.slice(0, first), spec.slice(first + 1, second), spec.slice(second + 1))
 }
 
-function parse_findings(specs: ReadonlyArray<string>): ReadonlyArray<Finding> | undefined {
+interface Positional {
+	finding: Finding
+	description: string
+}
+
+// A positional is `[<disposition> ]<spec>[ — <reason>]`; the disposition rides into the ledger line.
+function parse_positional(positional: string): Positional | undefined {
+	const { spec: marked, description } = review_finding_text.split_description(positional)
+	const { disposition, spec } = review_finding_ledger.split_disposition(marked)
+	const finding = parse_finding(spec)
+
+	if (finding === undefined) return undefined
+
+	return { finding: disposition === undefined ? finding : { ...finding, disposition }, description }
+}
+
+function parse_findings(positionals: ReadonlyArray<string>): ReadonlyArray<Finding> | undefined {
 	const findings: Array<Finding> = []
 
-	for (const spec of specs) {
-		const finding = parse_finding(spec)
+	for (const positional of positionals) {
+		const parsed = parse_positional(positional)
 
-		if (finding === undefined) return undefined
+		if (parsed === undefined) return undefined
 
-		findings.push(finding)
+		findings.push(parsed.finding)
 	}
 
 	return findings
@@ -133,6 +181,8 @@ function usage_text(): string {
 		accepted_values('<category>', review_finding_ledger.CATEGORIES),
 		accepted_values('<severity>', review_finding_ledger.SEVERITIES),
 		FILE_HINT,
+		DISPOSITION_HINT,
+		REASON_HINT,
 	].join('\n')
 }
 
@@ -158,10 +208,25 @@ type CheckStatus = RecordVerdict['status']
 
 interface CheckMode {
 	status: (issue: number, root: string) => Promise<CheckStatus>
+	recorded: (issue: number) => Promise<string>
 	refusal: (issue: number) => string
 	not_required: string
 }
 
+// **A recorded code round also says whether `josh ship` reuses it** (joshuafolkken/kit#4763), from the
+// ship's own predicate, in the ship's three outcomes (joshuafolkken/kit#4878): reused as it stands,
+// reused with the moved files left to round 2, or reviewed again — so the lane runs it itself rather
+// than reading "recorded" as "done".
+async function code_recorded(issue: number): Promise<string> {
+	const answer = await review_lane_handover.answer_here(issue)
+
+	return [RECORDED_LINE, reuse_line(answer)].join('\n')
+}
+
+async function interaction_recorded(): Promise<string> {
+	return RECORDED_LINE
+}
+
 async function code_status(issue: number, root: string): Promise<CheckStatus> {
 	const verdict = await review_record.check(issue, root)
 
@@ -172,13 +237,15 @@ async function code_status(issue: number, root: string): Promise<CheckStatus> {
 const CHECK_MODES: Record<LineKind, CheckMode> = {
 	code: {
 		status: code_status,
+		recorded: code_recorded,
 		refusal: review_record.refusal_message,
 		not_required: NOT_REQUIRED_LINE,
 	},
 	interaction: {
 		status: review_interaction.status,
+		recorded: interaction_recorded,
 		refusal: review_interaction.refusal_message,
-		not_required: INTERACTION_NOT_REQUIRED_LINE,
+		not_required: review_record_interaction.NOT_REQUIRED_LINE,
 	},
 }
 
@@ -195,7 +262,7 @@ async function report_check(issue: number, mode: CheckMode, root: string): Promi
 		return FAILURE_EXIT_CODE
 	}
 
-	console.info(status === 'ok' ? RECORDED_LINE : mode.not_required)
+	console.info(status === 'ok' ? await mode.recorded(issue) : mode.not_required)
 
 	return 0
 }
@@ -212,54 +279,109 @@ async function run_check(parsed: Parsed, root: string): Promise<number> {
 	return await report_check(Number(issue), CHECK_MODES[kind_of(parsed)], root)
 }
 
-// **A comment that could not be posted fails the record**: it is the round's only copy, so a
-// swallowed refusal would read as a recorded round that exists nowhere.
-async function post_comment(issue: number, lines: ReadonlyArray<string>): Promise<number> {
-	try {
-		const url = await git_gh_issue_write.issue_comment(
-			String(issue),
-			review_comment_round.body_of(lines),
-		)
+// The closed issues' comment rounds ride this round's commit (`review-comment-round.ts`) — **except in a
+// lane child** (joshuafolkken/kit#5326): parallel lanes each wrote the same newly closed issue's file,
+// so their ships waited on each other's overlap and their merges with main conflicted on it.
+// `observations:flush` carries them for the lanes, on the default branch, in one pull request.
+async function carry_comment_rounds(root: string): Promise<void> {
+	if (lane_child_marker.is_child_of(root)) {
+		console.info(LANE_CARRY_LINE)
 
-		console.info(`Recorded ${String(lines.length)} review-finding line(s) in ${url.trim()}.`)
+		return
+	}
 
-		return 0
-	} catch (error) {
-		console.error(error instanceof Error ? error.message : String(error))
+	await review_comment_carry.carry_reported(root)
+}
 
-		return FAILURE_EXIT_CODE
-	}
+// The round lands in its own issue's file, so two lanes recording at once
+// write two files, and their pull requests never conflict on the ledger.
+interface AppendedRound {
+	issue: number
+	lines: ReadonlyArray<string>
+	root: string
+	kind: LineKind
+	findings: ReadonlyArray<Finding>
+	date: string
 }
 
-// The closed issues' comment rounds ride this round's commit (`review-comment-round.ts`). **A carry
-// that fails never fails the record**: this round is recorded, and the comment rounds wait for the
-// next run's.
-async function carry_comment_rounds(root: string): Promise<void> {
-	try {
-		const count = await review_comment_round.carry(root)
+// A code round opens with its boundary line (`review-finding-ledger.ts`), not counted as a finding line.
+function ledger_lines({ issue, lines, kind, date }: AppendedRound): ReadonlyArray<string> {
+	if (kind === 'interaction') return lines
 
-		if (count > 0) console.info(`Carried ${String(count)} ${CARRIED_LINE}`)
-	} catch (error) {
-		console.warn(`${CARRY_FAILED_LINE} ${error instanceof Error ? error.message : String(error)}`)
-	}
+	return [review_finding_ledger.round_line(date, issue), ...lines]
 }
 
-// The round lands in its own issue's file, so two lanes recording at once
-// write two files, and their pull requests never conflict on the ledger.
-async function append_round(
-	issue: number,
-	lines: ReadonlyArray<string>,
-	root: string,
-): Promise<number> {
+// A code round goes on to what its tree means for the ship (`review-record-code-round.ts`).
+async function append_round(round: AppendedRound): Promise<number> {
+	const { issue, lines, root, kind, findings } = round
 	const ledger_path = observation_ledger_home.issue_path(issue, root)
 
-	await observation_ledger_home.append(ledger_path, lines)
+	await observation_ledger_home.append(ledger_path, ledger_lines(round))
 	console.info(confirmation(lines.length, ledger_path))
 	await carry_comment_rounds(root)
 
+	if (kind === 'code') await review_record_code_round.follow(issue, root, findings)
+
 	return 0
 }
 
+// A code round recorded after the push goes to the issue unasked (`review-record-comment.ts`).
+async function write_round(
+	parsed: Parsed,
+	request: Request,
+	now: Date,
+	root: string,
+): Promise<number> {
+	const kind = kind_of(parsed)
+	const date = observation_ledger_home.ledger_date(now)
+	const lines = build_lines(request, date, kind)
+	const { issue, findings } = request
+
+	if (parsed.comment) return await review_record_comment.post(issue, lines)
+
+	if (kind === 'code' && (await review_record_comment.is_after_push())) {
+		return await review_record_comment.post_after_push({ issue, lines, root, findings })
+	}
+
+	return await append_round({
+		issue: request.issue,
+		lines,
+		root,
+		kind,
+		findings: request.findings,
+		date,
+	})
+}
+
+// The stop-log finding a positional carries, or `undefined` for one written without a reason.
+function reason_of(positional: string): StopFinding | undefined {
+	const parsed = parse_positional(positional)
+
+	if (parsed === undefined || parsed.description.length === 0) return undefined
+
+	const { finding, description } = parsed
+
+	return {
+		kind: `${finding.category}:${finding.severity}`,
+		location: finding.file,
+		sentence: review_finding_text.first_sentence(description),
+	}
+}
+
+function is_reason(finding: StopFinding | undefined): finding is StopFinding {
+	return finding !== undefined
+}
+
+// Recorded only once the round itself is, so the stop log never holds a round the ledger refused.
+function record_reasons(issue: number, positionals: ReadonlyArray<string>): void {
+	review_stop_log.record({
+		issue,
+		stage: RECORD_STAGE,
+		findings: positionals.map((positional) => reason_of(positional)).filter(is_reason),
+		is_fixed: true,
+	})
+}
+
 async function run_record(parsed: Parsed, now: Date, root: string): Promise<number> {
 	const request = parsed.comment && parsed.interaction ? undefined : to_request(parsed)
 
@@ -269,11 +391,11 @@ async function run_record(parsed: Parsed, now: Date, root: string): Promise<numb
 		return FAILURE_EXIT_CODE
 	}
 
-	const lines = build_lines(request, observation_ledger_home.ledger_date(now), kind_of(parsed))
+	const code = await write_round(parsed, request, now, root)
 
-	if (parsed.comment) return await post_comment(request.issue, lines)
+	if (code === 0) record_reasons(request.issue, parsed.positionals)
 
-	return await append_round(request.issue, lines, root)
+	return code
 }
 
 // **The default is the work tree the command runs in, a lane's inside a lane**.
@@ -301,6 +423,7 @@ const review_record_cli = {
 	accepted_values,
 	build_lines,
 	parse_finding,
+	parse_positional,
 	run,
 	usage_text,
 }

package/scripts/review/review-record-code-round.ts

@@ -0,0 +1,55 @@
+import { run_ship_detach } from '#scripts/run/ship/run-ship-detach'
+import type { Finding } from './review-finding-ledger'
+import { review_lane_handover } from './review-lane-handover'
+import { review_record_interaction } from './review-record-interaction'
+import { review_record_pinned } from './review-record-pinned'
+import { review_reviewed_tree } from './review-reviewed-tree'
+
+// What `josh review:record` does once a code round is on the ledger: it records the tree the verdict
+// stands for, which `josh ship` reuses while the tree holds still (`review-reviewed-tree.ts`), names
+// the ship next for a lane child (`review-lane-handover.ts`), names an interaction review its fixes
+// made due (`review-record-interaction.ts`), reads a `josh run:review --join` the lane skipped, and
+// starts `josh test:pinned` again on a tree its fixes moved (`review-record-pinned.ts`).
+
+const HIGH_SEVERITY = 'high'
+
+// The files whose finding the round could not have fixed in place — a High never is.
+function unsettled_files(findings: ReadonlyArray<Finding>): ReadonlyArray<string> {
+	return findings
+		.filter((finding) => finding.severity === HIGH_SEVERITY)
+		.map((finding) => finding.file)
+}
+
+// A lane child's round the ship reuses names the ship next (joshuafolkken/kit#4850), read after the
+// tree is stamped; the lines that follow name what is done before that ship.
+async function report_handover(issue: number): Promise<boolean> {
+	const is_handed_over = await review_lane_handover.is_handed_over(issue)
+
+	if (is_handed_over) console.info(review_lane_handover.NEXT_STEP_LINE)
+
+	return is_handed_over
+}
+
+// Only a lane child's round the ship will reuse restarts the check: the ship's own rounds run under its
+// supervisor, where nothing reads the answer and the check would hold cores the ship's gate waits on.
+function is_restarted_here(is_handed_over: boolean): boolean {
+	return is_handed_over && !run_ship_detach.is_supervised()
+}
+
+async function follow(
+	issue: number,
+	root: string,
+	findings: ReadonlyArray<Finding>,
+): Promise<void> {
+	await review_reviewed_tree.record(unsettled_files(findings))
+	const is_handed_over = await report_handover(issue)
+
+	await review_record_interaction.report_due(issue, root)
+	if (!is_restarted_here(is_handed_over)) return
+	await review_record_pinned.read_skipped_join(root)
+	await review_record_pinned.restart_if_moved(root)
+}
+
+const review_record_code_round = { follow }
+
+export { review_record_code_round }

package/scripts/review/review-record-comment.ts

@@ -0,0 +1,60 @@
+import { git_gh_issue_write } from '#scripts/gh/git-gh-issue-write'
+import { run_ship_probe } from '#scripts/run/ship/run-ship-probe'
+import { review_comment_round } from './review-comment-round'
+import type { Finding } from './review-finding-ledger'
+import { review_record_code_round } from './review-record-code-round'
+
+// The issue-comment half of `josh review:record`: a round kept on the issue rather than in the
+// observation ledger (`review-comment-round.ts` carries it there once the issue closes).
+
+const FAILURE_EXIT_CODE = 1
+const AFTER_PUSH_LINE =
+	'The branch is pushed and the tree is clean, so this round is recorded on the issue, not in the ledger — a ledger line would need a push of its own and restart CI.'
+
+interface CommentRound {
+	issue: number
+	lines: ReadonlyArray<string>
+	root: string
+	findings: ReadonlyArray<Finding>
+}
+
+// **A comment that could not be posted fails the record**: it is the round's only copy, so a
+// swallowed refusal would read as a recorded round that exists nowhere.
+async function post(issue: number, lines: ReadonlyArray<string>): Promise<number> {
+	try {
+		const url = await git_gh_issue_write.issue_comment(
+			String(issue),
+			review_comment_round.body_of(lines),
+		)
+
+		console.info(`Recorded ${String(lines.length)} review-finding line(s) in ${url.trim()}.`)
+
+		return 0
+	} catch (error) {
+		console.error(error instanceof Error ? error.message : String(error))
+
+		return FAILURE_EXIT_CODE
+	}
+}
+
+// **A code round recorded once the branch is pushed and the tree clean goes to the issue unasked**
+// (joshuafolkken/kit#4907): `josh run:review` pushed at the first green gate, and a ledger line now
+// would ride no commit of the run's but a push of its own, restarting CI. `--check` reads the issue's
+// comment rounds too (`review-record.ts`). The round still stamps its tree, so `josh ship` reuses it
+// as round 1.
+async function is_after_push(): Promise<boolean> {
+	return await run_ship_probe.is_pushed_clean()
+}
+
+async function post_after_push(round: CommentRound): Promise<number> {
+	console.info(AFTER_PUSH_LINE)
+	const code = await post(round.issue, round.lines)
+
+	if (code === 0) await review_record_code_round.follow(round.issue, round.root, round.findings)
+
+	return code
+}
+
+const review_record_comment = { is_after_push, post, post_after_push }
+
+export { review_record_comment }

package/scripts/review/review-record-interaction.ts

@@ -0,0 +1,35 @@
+import { error_text } from '#scripts/lib/error-message'
+import { review_interaction } from './review-interaction'
+
+// What `josh review:record` says about the interaction review (`review-interaction.ts`).
+//
+// **A round-1 fix can make the pass due after its brief opened** (joshuafolkken/kit#4835): the fix
+// reaches the run tooling the original change did not, so round 1 opened with `/code-review`'s brief
+// alone. A recorded code round reads the pass's status over the fixed tree and names its brief, so the
+// lane runs it before `josh ship` instead of the ship's review stage running it alone and stopping on
+// its finding. A status git could not read prints nothing — the merge gate still refuses a missing pass.
+
+const NOT_REQUIRED_LINE =
+	'No interaction review is due: the change touches no run tooling, or this checkout keeps no ledger.'
+const DUE_HEAD = 'Interaction review now due'
+
+// An interaction reviewer that already ran beside round 1 is only recorded, never run twice.
+function due_line(issue: number): string {
+	return `${DUE_HEAD}: this round’s change touches the run tooling and no interaction pass is recorded. Before \`josh ship\`, record it with \`pnpm josh review:record --interaction --issue ${String(issue)} [<finding> ...]\` — if no interaction reviewer ran beside this round, first open its brief with \`pnpm josh review:brief --interaction\` and run that \`reviewer\` — so a finding is fixed in this lane rather than stopping the ship.`
+}
+
+async function report_due(issue: number, root: string): Promise<void> {
+	try {
+		if ((await review_interaction.status(issue, root)) === 'missing') console.info(due_line(issue))
+	} catch (error) {
+		error_text.trace_swallowed('review_record_interaction.report_due', error)
+	}
+}
+
+const review_record_interaction = {
+	due_line,
+	NOT_REQUIRED_LINE,
+	report_due,
+}
+
+export { review_record_interaction }

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

@@ -0,0 +1,108 @@
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { lane_child_marker } from '#scripts/lane/lane-child-marker'
+import { error_text } from '#scripts/lib/error-message'
+import { observation_ledger_home } from '#scripts/observations/observation-ledger-home'
+import { run_review_join_read, type JoinVerdict } from '#scripts/run/review/run-review-join-read'
+import { run_review_pinned_join } from '#scripts/run/review/run-review-pinned-join'
+import { run_ship_detach } from '#scripts/run/ship/run-ship-detach'
+import { test_pinned_logic } from '#scripts/test/test-pinned-logic'
+import { review_finding_ledger } from './review-finding-ledger'
+
+// What `josh review:record` does about the background `josh test:pinned` (joshuafolkken/kit#4834).
+//
+// **A round-1 fix can add hunks the check never read**: `josh run:review` launched it on the briefed
+// tree, and its join closed before the fix. The ship's pre-detach was then the first to name the fixed
+// tree's unpinned places, and stopped on them. A recorded code round compares the fixed tree with the
+// launch's and, where they differ, starts the check again with the launch's `--unpinned-ok` reason and
+// says who reads its answer. **Nothing waits on it in the foreground** (joshuafolkken/kit#4895): the
+// ship's pre-detach reads that same check's answer on that tree rather than running its own
+// (`run-review-pinned-join.ts`). A foreground read stalled the lane for minutes, and pinning what it
+// named moved the tree again under the next probe.
+//
+// **The same tree starts nothing**, and so does a tree either side could not read, or a checkout with
+// no launch. The fix's first `josh check:related` runs this same restart (joshuafolkken/kit#4948), so a
+// record on the tree it checked takes over the check already running there. `check:related` alone
+// waits on the check it started (joshuafolkken/kit#4987), within a bound that keeps the verdict line
+// under a foreground Bash call's cap (`check-related-pinned.ts`).
+
+function started_line(): string {
+	return `test:pinned restarted in the background on the tree this round's fixes moved. Where it names unpinned places, the ship's pre-detach stops on them: pin each with a test that turns red without it, or ship with \`--unpinned-ok "<reason>"\`.`
+}
+
+// `root` is the checkout `josh run:review` keyed its launch to: the ledger root `review:record` writes
+// under is the same working directory, and a test's temporary root holds no launch. Answers whether a
+// check was started.
+async function restart_if_moved(root: string = PROJECT_ROOT): Promise<boolean> {
+	try {
+		const is_started = await run_review_pinned_join.restart_if_moved(root)
+
+		if (is_started) console.info(started_line())
+
+		return is_started
+	} catch (error) {
+		error_text.trace_swallowed('review_record_pinned.restart_if_moved', error)
+
+		return false
+	}
+}
+
+// **A join the lane skipped is read here** (joshuafolkken/kit#5212): `josh run:review --join` was never
+// run, so the unpinned places would surface only as the ship's pre-detach failure. It reads only an
+// answer already left on this tree, so nothing waits on it either. A read that stops nothing prints
+// nothing, and a join already read changes nothing.
+const CHOICE_LINE =
+	'Unpinned before the ship: pin each place above with a test that turns red without it, or ship with `--unpinned-ok "<reason>"`.\n'
+
+function show_stop(joined: JoinVerdict | undefined): void {
+	if (joined?.is_stop !== true) return
+	console.info(test_pinned_logic.report_text(joined.summary, CHOICE_LINE).trimEnd())
+}
+
+async function read_skipped_join(root: string = PROJECT_ROOT): Promise<void> {
+	try {
+		if (run_review_join_read.is_due(root)) show_stop(await run_review_join_read.read_finished(root))
+	} catch (error) {
+		error_text.trace_swallowed('review_record_pinned.read_skipped_join', error)
+	}
+}
+
+// Whether the lane's code round is on the ledger: from then on `review:record` owns the restart, behind
+// its own handover guard.
+async function is_round_recorded(root: string): Promise<boolean> {
+	const issue = lane_child_marker.marked_issue()
+	if (issue === undefined) return false
+	const content = await observation_ledger_home.read(root)
+
+	return content !== undefined && review_finding_ledger.has_issue_record(content, Number(issue))
+}
+
+// `josh check:related`'s restart (joshuafolkken/kit#4948) runs only in a lane child outside a ship's
+// supervisor and before its round 1 is recorded: a launch record outlives its issue in a reused
+// checkout, and a child relaunched after a ship stop may re-detach without `--review`, which reads no
+// answer.
+async function is_restartable_before_record(root: string): Promise<boolean> {
+	if (!lane_child_marker.is_child_of(root) || run_ship_detach.is_supervised()) return false
+
+	return !(await is_round_recorded(root))
+}
+
+// Answers whether a check was started, so `check:related` waits on its answer (joshuafolkken/kit#4987).
+async function restart_in_lane(root: string = PROJECT_ROOT): Promise<boolean> {
+	try {
+		return (await is_restartable_before_record(root)) && (await restart_if_moved(root))
+	} catch (error) {
+		error_text.trace_swallowed('review_record_pinned.restart_in_lane', error)
+
+		return false
+	}
+}
+
+const review_record_pinned = {
+	CHOICE_LINE,
+	read_skipped_join,
+	restart_if_moved,
+	restart_in_lane,
+	started_line,
+}
+
+export { review_record_pinned }

package/scripts/review/review-record.ts

@@ -1,5 +1,6 @@
 import { session_cite } from '#scripts/issue/session-cite'
 import { observation_ledger_home } from '#scripts/observations/observation-ledger-home'
+import { review_comment_round } from './review-comment-round'
 import { review_finding_ledger } from './review-finding-ledger'
 
 // The gate that refuses a merge until the `/code-review` round was recorded.
@@ -33,14 +34,37 @@ interface RecordVerdict {
 // lane. Every file of the directory is read, so the round is found whichever
 // file holds it; a directory that is not there answers `undefined`, a ledger this checkout does not
 // keep, which becomes `not-required`.
+//
+// **A round recorded on the issue counts too** (`josh review:record --comment`): a round that ran after
+// the branch was pushed keeps its lines there so CI does not restart (joshuafolkken/kit#4907). Comments
+// that could not be read are no record — the refusal stands.
+type CommentLines = (issue: number) => Promise<ReadonlyArray<string>>
+
+async function has_comment_record(issue: number, read: CommentLines): Promise<boolean> {
+	try {
+		const lines = await read(issue)
+
+		return review_finding_ledger.has_issue_record(lines.join('\n'), issue)
+	} catch {
+		return false
+	}
+}
+
+async function is_recorded(content: string, issue: number, read: CommentLines): Promise<boolean> {
+	if (review_finding_ledger.has_issue_record(content, issue)) return true
+
+	return await has_comment_record(issue, read)
+}
+
 async function check(
 	issue: number,
 	root: string = observation_ledger_home.ledger_root(),
+	read_comment_lines: CommentLines = review_comment_round.issue_lines,
 ): Promise<RecordVerdict> {
 	const content = await observation_ledger_home.read(root)
 
 	if (content === undefined) return { status: 'not-required' }
-	if (review_finding_ledger.has_issue_record(content, issue)) return { status: 'ok', issue }
+	if (await is_recorded(content, issue, read_comment_lines)) return { status: 'ok', issue }
 
 	return { status: 'missing', issue }
 }