@joshuafolkken/kit 1.1514.0 → 1.1784.0

package/scripts/run/ship/run-ship-relaunch-cap.ts

@@ -0,0 +1,70 @@
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { RUN_STALLED_LABEL } from '#scripts/issue/issue-labels'
+import { issue_park } from '#scripts/issue/issue-park'
+import { telegram_notify } from '#scripts/notify/telegram-notify'
+import { run_event_scope } from '#scripts/run/event/run-event-scope'
+import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-stream'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
+import { run_stalled } from '#scripts/run/park/run-stalled'
+
+// How many times a stopped ship relaunches its lane child before the issue goes to a person. A child
+// that keeps stopping — the same red check, a finding it cannot close — would otherwise relaunch
+// without end, one ship's cost each time, with nobody told (joshuafolkken/kit#3999).
+//
+// **The count is the issue's `ship-stop` events since its last fresh dispatch**: a relaunch into the
+// lane emits no `child-launch`, a dispatch does, so a re-dispatched issue starts a new budget. The
+// current stop is emitted before the count is read, so it is part of it. Past the cap the issue is
+// parked with `run:stalled`, which every offer and the lane broker already refuse to start.
+// The whole stream is read, not the run's carry scope: the count scopes itself by issue and dispatch,
+// and a lane child shipping with no carry record (`lane:dispatch` outside a run, or a run already
+// ended) would otherwise read no events and relaunch without a cap.
+
+// One dispatch's own stops in the measured week reached five once and four or fewer otherwise, so four
+// relaunches leave a ship that converges alone and stop the one that does not.
+const MAX_SHIP_STOP_RELAUNCHES = 4
+const PARK_CAUSE = 'ship-stop cap'
+const { CHILD_LAUNCH, PARK, SHIP_STOP } = run_event_stream.EVENT_KIND
+
+function stops_since_dispatch(events: ReadonlyArray<RunEvent>, issue: string): number {
+	const own = events.filter((event) => run_event_scope.issue_named(event) === issue)
+	const dispatched = own.findLastIndex((event) => event.kind === CHILD_LAUNCH)
+
+	return own.slice(dispatched + 1).filter((event) => event.kind === SHIP_STOP).length
+}
+
+async function is_over(issue: string): Promise<boolean> {
+	const events = await run_event_stream_emit.all_events()
+
+	return stops_since_dispatch(events, issue) > MAX_SHIP_STOP_RELAUNCHES
+}
+
+function park_comment(issue: string, reason: string): string {
+	return [
+		`Parked by the \`josh ship\` supervisor: the ship stopped at \`${reason}\` after ${String(MAX_SHIP_STOP_RELAUNCHES)} relaunches of the lane child since its dispatch.`,
+		'',
+		`Read the stop with \`pnpm josh ship --log ${issue}\`, then ${run_stalled.next_step(issue)}.`,
+	].join('\n')
+}
+
+// The label is what keeps the issue from being re-dispatched; without it the stop stays a plain stop,
+// which `run:merge` books as an unanswered ship stop under its own outage cap.
+async function park(issue: string, reason: string): Promise<boolean> {
+	const park_write = await issue_park.apply(issue, RUN_STALLED_LABEL, park_comment(issue, reason))
+
+	if (!park_write.is_labelled) return false
+
+	const cite = issue_cite.plain(issue)
+
+	await run_event_stream_emit.emit(PARK, run_stalled.park_event(issue, PARK_CAUSE))
+	await telegram_notify.warn({
+		issue_title: `Ship stop cap reached ${cite}`,
+		body: `The lane child stopped at ${reason} more than ${String(MAX_SHIP_STOP_RELAUNCHES)} times since its dispatch, so it was not relaunched and the issue is parked.`,
+		recovery: `Read pnpm josh ship --log ${issue}, then fix the cause and remove ${RUN_STALLED_LABEL} to offer it again.`,
+	})
+
+	return true
+}
+
+const run_ship_relaunch_cap = { MAX_SHIP_STOP_RELAUNCHES, is_over, park, stops_since_dispatch }
+
+export { run_ship_relaunch_cap }

package/scripts/run/ship/run-ship-removed-rows.ts

@@ -0,0 +1,61 @@
+import { readFile, writeFile } from 'node:fs/promises'
+import { git_branch } from '#scripts/git/git-branch'
+import { git_command } from '#scripts/git/git-command'
+import { removed_tests } from '#scripts/review/removed-tests'
+import { removed_tests_check } from '#scripts/review/removed-tests-check'
+import { run_ship_body_draft } from './run-ship-body-draft'
+
+// **The tests a change removed, shown where a run passes before `josh ship`** — the end of a green
+// `josh test:related`. Their disposition rows were first asked at the ship's preflight, after the
+// pre-detach checks had run, and every lane that renamed a test stopped there and shipped again
+// (joshuafolkken/kit#4563). The removed titles are `removed_tests_check.read()`'s, and the pending
+// rows go into the branch's ship body draft, so the run only replaces each ending; the preflight still
+// refuses a row left pending.
+
+async function draft_of_branch(): Promise<string | undefined> {
+	const issue_number = git_branch.issue_from_branch(await git_command.branch())
+
+	if (issue_number === undefined) return undefined
+
+	return await run_ship_body_draft.existing(String(issue_number))
+}
+
+async function body_of(draft: string | undefined): Promise<string> {
+	return draft === undefined ? '' : await readFile(draft, 'utf8')
+}
+
+// An unreadable base lists nothing here — the preflight refuses on it — and outside a repository it
+// keeps the branch, which git could not answer, from being asked at all.
+async function removed_titles(): Promise<ReadonlyArray<string>> {
+	return (await removed_tests_check.read()) ?? []
+}
+
+function where(draft: string | undefined): string {
+	return draft === undefined
+		? 'Put these rows into the pull request body'
+		: `Pending rows for them are in the ship body draft ${draft}`
+}
+
+function notice(titles: ReadonlyArray<string>, draft: string | undefined): string {
+	return [
+		`Removed tests — this change removes ${String(titles.length)} test(s) the ship body does not dispose of yet. ${where(draft)}; replace each ending, ${removed_tests.ROW_FORMAT}, or the \`josh ship\` preflight refuses:`,
+		...titles.map((title) => `  - ${title}`),
+	].join('\n')
+}
+
+async function surface(): Promise<void> {
+	const removed = await removed_titles()
+
+	if (removed.length === 0) return
+	const draft = await draft_of_branch()
+	const body = await body_of(draft)
+	const titles = removed_tests.undisposed(removed, body)
+
+	if (titles.length === 0) return
+	if (draft !== undefined) await writeFile(draft, removed_tests.with_pending_rows(body, titles))
+	console.info(notice(titles, draft))
+}
+
+const run_ship_removed_rows = { surface }
+
+export { run_ship_removed_rows }

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

@@ -1,3 +1,4 @@
+import { setTimeout as sleep } from 'node:timers/promises'
 import { agent_role_profile } from '#scripts/agent/agent-role-profile'
 import { lane_child_invocation, type ShipStop } from '#scripts/lane/lane-child-invocation'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
@@ -8,8 +9,12 @@ import { run_event_stream } from '#scripts/run/event/run-event-stream'
 import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
 import type { ShipSection } from './run-ship'
 import { run_ship_next, type ShipResume } from './run-ship-next'
+import { run_ship_place } from './run-ship-place'
+import { run_ship_probe } from './run-ship-probe'
+import { run_ship_relaunch_cap } from './run-ship-relaunch-cap'
 import { run_ship_stage, type Stage } from './run-ship-stage'
 import type { ShipArguments } from './run-ship-steps'
+import { run_ship_stop_cause } from './run-ship-stop-cause'
 import { run_ship_stop_context } from './run-ship-stop-context'
 import { run_ship_stop_text } from './run-ship-stop-text'
 
@@ -25,16 +30,26 @@ import { run_ship_stop_text } from './run-ship-stop-text'
 //    effort because a fix is judgement. It is started before the supervisor exits, so the parent's
 //    liveness poll never sees the lane empty. An OpenAI lane is left to its own supervisor, which starts
 //    no successor without a cut, so its parent books the stop exactly as it books any ended child.
+//    The relaunches are capped: past the cap the issue is parked and a person told instead.
 //
 // A ship run in an agent's own turn is not supervised and hands nothing back: its report is already in
 // front of the agent that ran it.
 
 const OPENAI_PROVIDER = 'openai'
+// A minute of polling, long enough for the supervisor's 5-second lane scan to reopen a server.
+const SERVING_POLL_MS = 1000
+const SERVING_POLLS = 60
 
-type ReturnOutcome = 'relaunched' | 'recorded'
+type ReturnOutcome = 'relaunched' | 'recorded' | 'parked' | 'redispatch'
 
-function stop_text(issue: string, stage: Stage, resume: ShipResume): string {
-	return run_ship_stop_text.format(issue, run_ship_stage.stop_reason(stage, resume.conflicts))
+// The failed stage's output, and its standard output alone where the stage kept it apart.
+type StageOutput = Pick<ShipSection, 'body' | 'out'>
+
+function stop_text(issue: string, stage: Stage, resume: ShipResume, output: StageOutput): string {
+	const reason = run_ship_stage.stop_reason(stage, resume.conflicts)
+	const cause = run_ship_stop_cause.cause_of(stage, { ...resume, ...output })
+
+	return run_ship_stop_text.format(issue, reason, cause)
 }
 
 function can_relaunch(lane: LaneInfo | undefined): lane is LaneInfo {
@@ -68,56 +83,125 @@ function relaunched(lane: LaneInfo, stop: ShipStop): ReturnOutcome {
 // **A served lane's child is relaunched by its broker, not from here**: this supervisor descends from the
 // child's Bash tool, which Claude Code starts without the token, so a child started here could not sign
 // in where the token is the only credential (joshuafolkken/kit#3817).
-async function brokered(lane: LaneInfo, stop: ShipStop): Promise<ReturnOutcome> {
+async function ask_broker(lane: LaneInfo, stop: ShipStop): Promise<boolean> {
 	const answer = await lane_session_broker.request(lane.directory, lane.issue, {
 		kind: 'relaunch',
 		stop,
 	})
 
-	if (answer.is_success) return 'relaunched'
+	if (!answer.is_success) note(`the lane broker did not start the lane child — ${answer.reason}`)
 
-	note(
-		`the lane child could not be relaunched: the lane broker did not start it — ${answer.reason}`,
-	)
+	return answer.is_success
+}
+
+// The session of a broker serving the lane within the wait, other than `previous` — one that stopped
+// serving is reopened by the supervisor's next lane scan (`claude-lane-broker.ts`).
+async function await_server(lane: LaneInfo, previous?: string): Promise<string | undefined> {
+	for (let polled = 0; polled < SERVING_POLLS; polled += 1) {
+		const session = lane_session_broker.serving_session(lane.directory, lane.issue)
+		if (session !== undefined && session !== previous) return session
+
+		// eslint-disable-next-line no-await-in-loop -- polling: each check waits on the scan the previous one missed
+		await sleep(SERVING_POLL_MS)
+	}
+
+	return undefined
+}
+
+// **A relaunch the broker failed is asked once more, of a new broker only, then handed to the driver**: a
+// stop left recorded waited hours for the stall detector (joshuafolkken/kit#4344). The broker that failed
+// may still be starting the first relaunch, so asking it again could start a second child beside it.
+// Once this supervisor exits, the driver's next poll reads the stop as unanswered and re-dispatches the
+// issue (`run-merge-ship.ts`).
+async function brokered(lane: LaneInfo, stop: ShipStop, server: string): Promise<ReturnOutcome> {
+	if (await ask_broker(lane, stop)) return 'relaunched'
+
+	const next = await await_server(lane, server)
+
+	if (next !== undefined && (await ask_broker(lane, stop))) return 'relaunched'
+
+	note('the lane child could not be relaunched: the driver re-dispatches the issue')
+
+	return 'redispatch'
+}
+
+// A child that stopped more often than the cap allows is parked instead of relaunched
+// (`run-ship-relaunch-cap.ts`); a park the label refused leaves the stop recorded, as before.
+async function parked(issue: string, stage: Stage, resume: ShipResume): Promise<ReturnOutcome> {
+	const reason = run_ship_stage.stop_reason(stage, resume.conflicts)
+
+	if (await run_ship_relaunch_cap.park(issue, reason)) return 'parked'
+
+	note('the lane child was not relaunched past the ship-stop cap, and the park label was refused')
 
 	return 'recorded'
 }
 
-// `output` is the failed stage's own output: the relaunched child's prompt carries its tail.
-async function return_control(
+// `output` is the failed stage's own output: the relaunched child's prompt carries the body's tail, and
+// the stop is classified on its standard output (`run-ship-stop-cause.ts`).
+async function stopped(
 	issue: string,
 	stage: Stage,
 	resume: ShipResume,
-	output: string,
+	output: StageOutput,
 ): Promise<ReturnOutcome> {
 	await run_event_stream_emit.emit(
 		run_event_stream.EVENT_KIND.SHIP_STOP,
-		stop_text(issue, stage, resume),
+		stop_text(issue, stage, resume, output),
 	)
 
 	const lane = await lane_to_relaunch(issue)
 
 	if (lane === undefined) return 'recorded'
 
-	const stop = { stage, ...resume, context: await run_ship_stop_context.build(issue, output) }
+	if (await run_ship_relaunch_cap.is_over(issue)) return await parked(issue, stage, resume)
+	// A followup stop waits for a lane place, keeping the ship-stop prompt and the relaunch cap a driver
+	// re-dispatch would lose (`run-ship-place.ts`).
+	await run_ship_place.await_place(lane, stage)
+
+	const context = await run_ship_stop_context.build(issue, output.body)
+	const stop = { stage, ...resume, context }
+	// **A broker that stopped serving before the stop is waited for**: one that died during the review left
+	// the lane unserved at the stop, and a child started here cannot sign in on a token (joshuafolkken/kit#4344).
+	const server = await await_server(lane)
+
+	return server === undefined ? relaunched(lane, stop) : await brokered(lane, stop, server)
+}
+
+async function return_control(
+	issue: string,
+	stage: Stage,
+	resume: ShipResume,
+	output: string,
+): Promise<ReturnOutcome> {
+	return await stopped(issue, stage, resume, { body: output })
+}
+
+type FailedSection = Pick<ShipSection, 'body' | 'out' | 'conflicts' | 'cause'>
+
+// The section's conflicts and the cause its review round tagged, only where it has them.
+function stopped_resume(resume: ShipResume, failed: FailedSection | undefined): ShipResume {
+	const { conflicts, cause } = failed ?? {}
 
-	return lane_session_broker.is_serving(lane.directory, issue)
-		? await brokered(lane, stop)
-		: relaunched(lane, stop)
+	return {
+		...resume,
+		...(conflicts !== undefined && { conflicts }),
+		...(cause !== undefined && { cause }),
+	}
 }
 
-// The stopped ship's arguments and its failed section, as `return_control` takes them: the section's
-// conflicts ride on the resume, its body is the output the prompt carries.
+// The stopped ship's arguments and its failed section, as `stopped` takes them: the section's conflicts
+// and tagged cause ride on the resume, its body and standard output are the stage's output. A stale
+// review rides on it too, so the relaunched child re-detaches with `--review` (joshuafolkken/kit#4221).
 async function hand_back(
 	args: ShipArguments,
 	stage: Stage,
-	failed: Pick<ShipSection, 'body' | 'conflicts'> | undefined,
+	failed: FailedSection | undefined,
 ): Promise<ReturnOutcome> {
-	const resume = run_ship_next.resume_of(args)
-	const conflicts = failed?.conflicts
-	const stopped = conflicts === undefined ? resume : { ...resume, conflicts }
+	const is_review_stale = await run_ship_probe.read_review_stale()
+	const resume = { ...run_ship_next.resume_of(args), is_review_stale }
 
-	return await return_control(args.number, stage, stopped, failed?.body ?? '')
+	return await stopped(args.number, stage, stopped_resume(resume, failed), failed ?? { body: '' })
 }
 
 const run_ship_return = { hand_back, return_control }

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

@@ -1,14 +1,13 @@
-import { agent_argv, type AgentArgv } from '#scripts/agent/agent-argv'
-import { agent_role_profile, type AgentProfile } from '#scripts/agent/agent-role-profile'
-import { PROJECT_ROOT } from '#scripts/init/init-paths'
-import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
+import type { JoshResult } from '#scripts/josh/josh-run'
 import { stamp_file } from '#scripts/josh/stamp-file'
-import { lane_child_marker } from '#scripts/lane/lane-child-marker'
-import { lane_session_broker } from '#scripts/lane/lane-session-broker'
+import { lane_ledger } from '#scripts/lane/lane-ledger'
+import { review_interaction } from '#scripts/review/review-interaction'
 import { review_record } from '#scripts/review/review-record'
-import { detached_launch } from '#scripts/run/detached-launch'
+import { review_round2 } from '#scripts/review/review-round2'
 import { run_ship_review, type RoundOutcome, type ScoredVerdict } from './run-ship-review'
-import { run_ship_scoped, type Phase } from './run-ship-scoped'
+import { run_ship_reviewer, type Round } from './run-ship-reviewer'
+import { run_ship_scoped } from './run-ship-scoped'
+import { run_ship_stop_cause } from './run-ship-stop-cause'
 import type { StepResult } from './run-ship-sync'
 
 // The side effects of `josh ship --review`: the round-1 review — open, launch, join, attest and
@@ -17,7 +16,8 @@ import type { StepResult } from './run-ship-sync'
 //
 // 1. `run:review` starts the gate detached and mints the brief — the nonce `review:attest` checks.
 // 2. the reviewer is launched the way `run:wake` launches a session — `agent_argv` under the reviewer
-//    profile, `detached_launch.launch_attached` to wait for its exit — handed the brief by path.
+//    profile, `detached_launch.launch_attached` to wait for its exit — handed the brief by path
+//    (`run-ship-reviewer.ts`).
 // 3. `run:review --join` blocks a verdict over a red gate; `review:attest --check` refuses a review
 //    that read another checkout; `review:record` writes the round the merge gate reads.
 //
@@ -36,19 +36,15 @@ import type { StepResult } from './run-ship-sync'
 // unreadable findings file, a High or an unfixed Medium in round 1, and anything but a clean round 2 —
 // recorded first, because the round was attested, then routed back.
 
-const SUCCESS_EXIT_CODE = 0
-const FAILURE_EXIT_CODE = 1
-const should_forward_stderr = true
 const RUN_REVIEW = 'run:review'
-const ATTEST_CHECK = ['review:attest', '--check']
-const ROUND_TWO_DECISION = ['review:round2', '--round-1-closed']
-const ROUND_TWO_BRIEF = ['review:brief', '--round', '2']
-const ROUND_TWO_REQUIRED = 'required'
-const ROUND_ONE = '1'
-const ROUND_TWO = '2'
+const ROUND_TWO_DECISION = ['review:round2', '--round-1-closed', '--json']
+const REVIEW_BRIEF = 'review:brief'
+const ROUND_TWO_BRIEF = [REVIEW_BRIEF, '--round', '2']
+const INTERACTION_FLAG = '--interaction'
+const INTERACTION_BRIEF = [REVIEW_BRIEF, INTERACTION_FLAG]
+const UNREADABLE_DECISION_NOTE = 'review:round2 printed no decision josh ship can read:'
 const COMMENT_FLAG = '--comment'
 
-type Round = typeof ROUND_ONE | typeof ROUND_TWO
 const FIXED_JOIN_NOTE =
 	'the round-1 gate read the tree before the review fixes — drained, not judged; the gate re-runs once the tree is fixed.'
 const ROUND_TWO_SKIPPED_NOTE = 'round 2 not due — nothing left to verify; shipping on.'
@@ -58,99 +54,21 @@ const ROUND_ONE_RECORDED_NOTE =
 // The scoped pair's precondition, met by the supervisor itself rather than stopped on,
 // single-sourced with the preflight and gate stages.
 const { run_phases, scoped_pair } = run_ship_scoped
-
-type PromptOf = (brief_path: string, findings_path: string, issue: string) => string
-
-function failure(out: string): JoshResult {
-	return { code: FAILURE_EXIT_CODE, out }
-}
-
-function paths(): { brief: string; findings: string; log: string } {
-	return lane_session_broker.review_paths(PROJECT_ROOT)
-}
-
-async function josh(argv: ReadonlyArray<string>): Promise<JoshResult> {
-	return await josh_command.josh_run(argv, should_forward_stderr)
-}
-
-function note(text: string): void {
-	process.stderr.write(`${text}\n`)
-}
-
-// Under the round's reviewer profile — the same model and effort (`JOSH_REVIEWER_*` included) the
-// chain's subagent is given — and waited on, so the join below runs only once the review has finished.
-// Each call is its own process, so round 2 is a fresh session by construction.
-async function run_direct_session(
-	argv: AgentArgv,
-	profile: AgentProfile,
-	log_path: string,
-	round: Round,
-): Promise<JoshResult> {
-	const request = { argv, cwd: PROJECT_ROOT, log_path, profile }
-
-	note(agent_role_profile.describe_review(Number(round), profile))
-	const result = await detached_launch.launch_attached(request, note)
-
-	if (result.kind === 'failed') return failure(`reviewer could not start: ${result.note}`)
-	if (result.exit_code !== SUCCESS_EXIT_CODE) return failure(`reviewer failed — log: ${log_path}`)
-
-	return { code: SUCCESS_EXIT_CODE, out: '' }
-}
-
-// A lane child's reviewer is started by the lane's broker: an OpenAI lane's always, since a nested Codex
-// cannot write outside its sandbox, and a Claude lane's whenever the `run:wake` supervisor serves it, since this
-// ship was started from the child's Bash tool and so never received a token-only credential
-// (joshuafolkken/kit#3817). A Claude lane nobody serves starts the reviewer itself, as before.
-function is_brokered(profile: AgentProfile, issue: string): boolean {
-	if (!lane_child_marker.is_child_of(PROJECT_ROOT)) return false
-
-	return profile.provider === 'openai' || lane_session_broker.is_serving(PROJECT_ROOT, issue)
-}
-
-async function run_session(
-	prompt: string,
-	log_path: string,
-	issue: string,
-	round: Round,
-): Promise<JoshResult> {
-	const built = agent_argv.review_in(prompt, Number(round), PROJECT_ROOT)
-	if (built.kind === 'rejected') return failure(`reviewer profile rejected: ${built.note}`)
-
-	if (!is_brokered(built.profile, issue)) {
-		return await run_direct_session(built.argv, built.profile, log_path, round)
-	}
-
-	const answer = await lane_session_broker.request(PROJECT_ROOT, issue, { kind: 'review', round })
-
-	return answer.is_success
-		? { code: SUCCESS_EXIT_CODE, out: '' }
-		: failure(`isolated reviewer failed: ${answer.reason}`)
-}
-
-// The brief goes to a file and the previous round's findings are removed, so a reviewer that writes
-// nothing reads as unfinished rather than as the last round's verdict.
-async function launch_reviewer(
-	brief: string,
-	prompt_of: PromptOf,
-	issue: string,
-	round: Round,
-): Promise<JoshResult> {
-	const target = paths()
-
-	stamp_file.write_text_stamp(target.brief, brief)
-	stamp_file.remove_stamp(target.findings)
-
-	return await run_session(
-		prompt_of(target.brief, target.findings, issue),
-		target.log,
-		issue,
-		round,
-	)
-}
-
-function current_verdict(): ReturnType<typeof run_ship_review.read_verdict> {
-	return run_ship_review.read_verdict(stamp_file.read_stamp_text(paths().findings))
-}
+const { CAUSE } = run_ship_stop_cause
+const {
+	attest_phase,
+	current_verdict,
+	failure,
+	josh,
+	note,
+	paths,
+	reviewed,
+	ROUND_ONE,
+	ROUND_TWO,
+	SUCCESS_EXIT_CODE,
+	tagged,
+	tagged_phase,
+} = run_ship_reviewer
 
 // A red join blocks unless the reviewer fixed findings in place: the background gate then read the
 // tree before the fixes, so its verdict describes a tree that no longer exists. The join still ran to
@@ -180,57 +98,42 @@ function record_flags(round: Round, outcome: RoundOutcome): ReadonlyArray<string
 	return round === ROUND_TWO && outcome.is_passing ? [COMMENT_FLAG] : []
 }
 
+// `kind` is the record's own flags — `--interaction` for the interaction review's `- ri:` line.
 async function record_and_route(
 	issue: string,
 	round: Round,
 	outcome_of: (verdict: ScoredVerdict) => RoundOutcome,
+	kind: ReadonlyArray<string> = [],
 ): Promise<JoshResult> {
 	const verdict = current_verdict()
 
-	if (verdict.kind === run_ship_review.VERDICT.INVALID) return failure(verdict.note)
+	if (verdict.kind === run_ship_review.VERDICT.INVALID) return failure(verdict.note, CAUSE.INFRA)
 
 	const outcome = outcome_of(verdict)
-	const flags = record_flags(round, outcome)
+	const flags = [...kind, ...record_flags(round, outcome)]
 	const recorded = await josh(['review:record', '--issue', issue, ...flags, ...verdict.specs])
 
-	if (recorded.code !== SUCCESS_EXIT_CODE) return recorded
+	if (recorded.code !== SUCCESS_EXIT_CODE) return tagged(CAUSE.CHECK, recorded)
 
 	const out = [...verdict.report, outcome.note].join('\n')
 
-	return outcome.is_passing ? { code: SUCCESS_EXIT_CODE, out } : failure(out)
-}
-
-// A brief-minting command, then a reviewer handed what it printed.
-function reviewed(
-	open: ReadonlyArray<string>,
-	prompt_of: PromptOf,
-	issue: string,
-	round: Round,
-): ReadonlyArray<Phase> {
-	const opened = { brief: '' }
-
-	return [
-		async () => {
-			const result = await josh(open)
-
-			opened.brief = result.out
-
-			return result
-		},
-		async () => await launch_reviewer(opened.brief, prompt_of, issue, round),
-	]
+	return outcome.is_passing ? { code: SUCCESS_EXIT_CODE, out } : failure(out, CAUSE.FINDING)
 }
 
 // Fixes made in place are counted only once the scoped pair is green on the fixed tree. The reviewer is
 // asked to leave it green; this is the check that it did, and a fix it could not get green is routed as
 // the finding it still is — recorded, then stopped before the gate and the commit take it in.
-async function round_one_record(issue: string): Promise<JoshResult> {
+async function round_one_record(issue: string, kind?: ReadonlyArray<string>): Promise<JoshResult> {
 	const is_fixed = current_verdict().kind === run_ship_review.VERDICT.FIXED
 	const checked = is_fixed ? await scoped_pair() : undefined
 	const is_verified = checked === undefined || checked.code === SUCCESS_EXIT_CODE
 
-	return await record_and_route(issue, ROUND_ONE, (verdict) =>
-		is_verified ? run_ship_review.round_one_outcome(verdict) : run_ship_review.UNVERIFIED_OUTCOME,
+	return await record_and_route(
+		issue,
+		ROUND_ONE,
+		(verdict) =>
+			is_verified ? run_ship_review.round_one_outcome(verdict) : run_ship_review.UNVERIFIED_OUTCOME,
+		kind,
 	)
 }
 
@@ -245,35 +148,86 @@ function skipped(out: string): StepResult {
 // **A recorded round 1 is not run again**. A ship relaunched with `--review`
 // after a round-1 stop would otherwise review the whole change a second time as round 1 — a new Medium
 // there stops it again, and round 2 after the commit makes a third. The fix delta is round 2's to
-// verify, and `round_two_stage` asks whether it is due after the commit.
-async function review_stage(issue: string): Promise<StepResult> {
+// verify, and `round_two_stage` asks whether it is due after the commit — unless the issue changed after
+// that round's brief: the recorded round then never read it, and `josh followup` refuses the merge on it
+// (joshuafolkken/kit#4221).
+async function round_one_stage(issue: string, is_stale: boolean): Promise<StepResult> {
 	const recorded = await review_record.check(Number(issue))
 
-	if (recorded.status === 'ok') return skipped(ROUND_ONE_RECORDED_NOTE)
+	if (!is_stale && recorded.status === 'ok') return skipped(ROUND_ONE_RECORDED_NOTE)
 
 	return await run_phases([
-		scoped_pair,
+		tagged_phase(CAUSE.CHECK, scoped_pair),
 		...reviewed([RUN_REVIEW], run_ship_review.reviewer_prompt, issue, ROUND_ONE),
-		join_gate,
-		async () => await josh(ATTEST_CHECK),
+		tagged_phase(CAUSE.CHECK, join_gate),
+		attest_phase,
 		async () => await round_one_record(issue),
 	])
 }
 
+// The interaction review (joshuafolkken/kit#4276): after round 1, over a change to the run tooling,
+// scoped pair → `review:brief --interaction` → reviewer → attest → `review:record --interaction`. Its
+// fixes are verified as round 1's are; no join, since round 1 already drained the gate.
+async function interaction_stage(issue: string): Promise<StepResult> {
+	return await run_phases([
+		tagged_phase(CAUSE.CHECK, scoped_pair),
+		...reviewed(INTERACTION_BRIEF, run_ship_review.reviewer_prompt, issue, ROUND_ONE),
+		attest_phase,
+		async () => await round_one_record(issue, [INTERACTION_FLAG]),
+	])
+}
+
+// Round 1, then the interaction review where it is due and not yet recorded — so a relaunched ship
+// whose round 1 is recorded still owes it. The first stop is returned as it is.
+async function review_stage(issue: string, is_stale = false): Promise<StepResult> {
+	const first = await round_one_stage(issue, is_stale)
+
+	if (
+		first.code !== SUCCESS_EXIT_CODE ||
+		(await review_interaction.status(Number(issue))) !== 'missing'
+	) {
+		return first
+	}
+
+	const second = await interaction_stage(issue)
+
+	if (second.code !== SUCCESS_EXIT_CODE) return second
+
+	return { code: SUCCESS_EXIT_CODE, out: [first.out, second.out].join('\n') }
+}
+
 // The round-2 verification pass, after the commit so it runs beside CI: due only when the round-1 fix
 // delta says so, then scoped pair → brief → fresh reviewer → attest → record.
+//
+// **The decision is read as JSON and recorded in the lane ledger before it is acted on**, so
+// `josh lane:stats` can count the period's round-2 runs and skips by their reason code
+// (joshuafolkken/kit#4064). Output it cannot parse stops the ship rather than guessing a verdict.
 async function round_two_stage(issue: string): Promise<StepResult> {
 	const decision = await josh(ROUND_TWO_DECISION)
-	const answer = decision.out.trim()
 
-	if (decision.code !== SUCCESS_EXIT_CODE) return decision
+	if (decision.code !== SUCCESS_EXIT_CODE) return tagged(CAUSE.CHECK, decision)
+
+	const answer = review_round2.parse_json(decision.out)
 
-	if (answer !== ROUND_TWO_REQUIRED) return skipped(`${answer}\n${ROUND_TWO_SKIPPED_NOTE}`)
+	if (answer === undefined) {
+		return failure(`${UNREADABLE_DECISION_NOTE}\n${decision.out}`, CAUSE.CHECK)
+	}
+
+	note(answer.reason)
+	await lane_ledger.record_round_two({
+		issue: Number(issue),
+		verdict: answer.verdict,
+		code: answer.code,
+	})
+
+	if (answer.verdict !== review_round2.REQUIRED_VERDICT) {
+		return skipped(`${answer.verdict}\n${ROUND_TWO_SKIPPED_NOTE}`)
+	}
 
 	return await run_phases([
-		scoped_pair,
+		tagged_phase(CAUSE.CHECK, scoped_pair),
 		...reviewed(ROUND_TWO_BRIEF, run_ship_review.verification_prompt, issue, ROUND_TWO),
-		async () => await josh(ATTEST_CHECK),
+		attest_phase,
 		async () => await record_and_route(issue, ROUND_TWO, run_ship_review.round_two_outcome),
 	])
 }