@joshuafolkken/kit 1.1471.0 → 1.1784.0

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,97 +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 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,
-): Promise<JoshResult> {
-	const request = { argv, cwd: PROJECT_ROOT, log_path, 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.resolve_in(prompt, agent_role_profile.REVIEWER, 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)
-	}
-
-	const is_success = await lane_session_broker.request(PROJECT_ROOT, issue, {
-		kind: 'review',
-		round,
-	})
-
-	return is_success ? { code: SUCCESS_EXIT_CODE, out: '' } : failure('isolated reviewer failed')
-}
-
-// 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
@@ -178,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,
 	)
 }
 
@@ -243,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 === 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 !== ROUND_TWO_REQUIRED) return skipped(`${answer}\n${ROUND_TWO_SKIPPED_NOTE}`)
+	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),
 	])
 }

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

@@ -23,12 +23,18 @@ const LINE_SEPARATOR = /\r?\n/u
 const HIGH = 'high'
 const MEDIUM = 'medium'
 const FIXED_PREFIX = 'fixed '
+const KIND_FIELDS = 2
 // What a finding line carries after its spec: one sentence saying what is wrong, so a stopped ship's
 // log tells the resumed lane child the defect rather than only its location.
 const DESCRIPTION_SEPARATOR = ' — '
 // Where the spec ends on read: a reviewer that types the dash as `-`, `--` or `–` still ends it there,
 // so its sentence never lands in the ledger's file field.
 const DESCRIPTION_BOUNDARY = / [—–-]{1,2} /u
+// Where a description's first sentence ends, and the cap that keeps a run-on one a line. Japanese
+// sets no space after `。`, so it ends a sentence on its own.
+const SENTENCE_END = /(?<=[.!?])\s|(?<=。)/u
+const SENTENCE_LIMIT = 200
+const ELLIPSIS = '…'
 
 const VERDICT = {
 	CLEAN: 'clean',
@@ -57,6 +63,15 @@ interface Finding {
 	spec: string
 	is_fixed: boolean
 	line: string
+	description: string
+}
+
+// One finding that decided a stopped review, as the durable stop log keeps it: its kind, the
+// `<file>[:<line>]` it cites and the first sentence of what it said (joshuafolkken/kit#4519).
+interface StopFinding {
+	kind: string
+	location: string
+	sentence: string
 }
 
 const MISSING_NOTE = 'the reviewer wrote no findings file — the review did not complete'
@@ -120,17 +135,30 @@ function verification_prompt(brief_path: string, findings_path: string, issue: s
 	].join(' ')
 }
 
-// The spec is what `review:record` reads; the description after it travels only in the stage output.
-function spec_of(unmarked: string): string {
-	const end = unmarked.search(DESCRIPTION_BOUNDARY)
+// The spec is what `review:record` reads; the description after it travels in the stage output and,
+// for a finding that stopped the ship, its first sentence in the durable stop log.
+function split_description(unmarked: string): { spec: string; description: string } {
+	const boundary = DESCRIPTION_BOUNDARY.exec(unmarked)
+
+	if (boundary === null) return { spec: unmarked.trim(), description: '' }
 
-	return (end === -1 ? unmarked : unmarked.slice(0, end)).trim()
+	const rest = unmarked.slice(boundary.index + boundary[0].length)
+
+	return { spec: unmarked.slice(0, boundary.index).trim(), description: rest.trim() }
 }
 
 function finding_of(line: string): Finding {
 	const is_fixed = line.startsWith(FIXED_PREFIX)
 
-	return { spec: spec_of(is_fixed ? line.slice(FIXED_PREFIX.length) : line), is_fixed, line }
+	return { ...split_description(is_fixed ? line.slice(FIXED_PREFIX.length) : line), is_fixed, line }
+}
+
+function first_sentence(description: string): string {
+	const [sentence = ''] = description.split(SENTENCE_END, 1)
+
+	if (sentence.length <= SENTENCE_LIMIT) return sentence
+
+	return `${sentence.slice(0, SENTENCE_LIMIT - ELLIPSIS.length)}${ELLIPSIS}`
 }
 
 function spec_findings(text: string): ReadonlyArray<Finding> {
@@ -153,6 +181,43 @@ function is_blocking(finding: Finding): boolean {
 	return severity === HIGH || (severity === MEDIUM && !finding.is_fixed)
 }
 
+function kind_of(finding: Finding): string {
+	return finding.spec.split(':', KIND_FIELDS).join(':')
+}
+
+function kinds_of(findings: ReadonlyArray<Finding>): ReadonlyArray<string> {
+	return [...new Set(findings.map((finding) => kind_of(finding)))]
+}
+
+function stop_finding_of(finding: Finding): StopFinding {
+	const location = review_record_cli.parse_finding(finding.spec)?.file ?? ''
+
+	return { kind: kind_of(finding), location, sentence: first_sentence(finding.description) }
+}
+
+// `bug-risks:medium` — each kind of finding that decided a stopped stage, once per kind (the stop
+// counts once under each in `lane:stats`), so the lane ledger records which kinds of finding stop a
+// lane rather than only that one did (joshuafolkken/kit#4426). The blocking findings decide it where
+// there are any; otherwise the stop was decided by the fixes — round-1 fixes red on the scoped pair, or
+// a round 2 that edited the tree — so the fixed findings do. A line outside the grammar is the stage's
+// own prose and never counts.
+function deciding_findings(text: string): ReadonlyArray<Finding> {
+	const findings = spec_findings(text).filter((finding) => is_recordable(finding))
+	const blocking = findings.filter((finding) => is_blocking(finding))
+
+	return blocking.length > 0 ? blocking : findings.filter((finding) => finding.is_fixed)
+}
+
+function blocking_kinds(text: string): ReadonlyArray<string> {
+	return kinds_of(deciding_findings(text))
+}
+
+// The same findings `blocking_kinds` counts, each one whole — every finding, not once per kind — so a
+// stop can be classified by what was found where, not only by its kind (joshuafolkken/kit#4519).
+function blocking_details(text: string): ReadonlyArray<StopFinding> {
+	return deciding_findings(text).map((finding) => stop_finding_of(finding))
+}
+
 function scored_kind(findings: ReadonlyArray<Finding>): ScoredVerdict['kind'] {
 	if (findings.some((finding) => is_blocking(finding))) return VERDICT.BLOCKING
 
@@ -216,6 +281,8 @@ const run_ship_review = {
 	FIXED_PREFIX,
 	UNVERIFIED_OUTCOME,
 	VERDICT,
+	blocking_details,
+	blocking_kinds,
 	has_fixes,
 	is_clean_round_one,
 	read_verdict,
@@ -225,5 +292,5 @@ const run_ship_review = {
 	verification_prompt,
 }
 
-export type { ReviewVerdict, RoundOutcome, ScoredVerdict }
+export type { ReviewVerdict, RoundOutcome, ScoredVerdict, StopFinding }
 export { run_ship_review }

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

@@ -0,0 +1,207 @@
+import { agent_argv, type AgentArgv } from '#scripts/agent/agent-argv'
+import { agent_role_profile, type AgentProfile } from '#scripts/agent/agent-role-profile'
+import { api_auth } from '#scripts/agent/api-auth'
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { josh_command, 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 { detached_launch } from '#scripts/run/detached-launch'
+import { run_ship_review } from './run-ship-review'
+import type { Phase } from './run-ship-scoped'
+import { run_ship_stop_cause, type Cause } from './run-ship-stop-cause'
+import type { StepResult } from './run-ship-sync'
+
+// The reviewer half of `josh ship --review` (`run-ship-review-steps.ts`): a brief-minting command, a
+// reviewer session handed what it printed, and the attestation that the session read this checkout.
+// Every review round the ship runs — round 1, the interaction review, round 2 — launches through here.
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const should_forward_stderr = true
+const ATTEST_CHECK = ['review:attest', '--check']
+const KEPT_REVIEW_NOTE =
+	'the reviewer wrote its findings before it failed — its review is kept; attest and record judge it.'
+type Round = '1' | '2'
+
+const ROUND_ONE: Round = '1'
+const ROUND_TWO: Round = '2'
+type PromptOf = (brief_path: string, findings_path: string, issue: string) => string
+
+const { CAUSE } = run_ship_stop_cause
+
+// **Every stop is tagged with the step's own cause**, so a round that stopped on a red join, a reviewer
+// that did not finish or a refused attestation is not booked as a finding (joshuafolkken/kit#4431).
+function failure(out: string, cause: Cause): StepResult {
+	return { code: FAILURE_EXIT_CODE, out, cause }
+}
+
+function tagged(cause: Cause, result: JoshResult): StepResult {
+	return result.code === SUCCESS_EXIT_CODE ? result : { ...result, cause }
+}
+
+function tagged_phase(cause: Cause, phase: Phase): Phase {
+	return async () => tagged(cause, await phase())
+}
+
+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`)
+}
+
+// A reviewer that could not authenticate is named as such (`api-auth.ts`), so the stop is not booked as
+// a review finding (joshuafolkken/kit#4216).
+function exited_note(log_path: string): string {
+	const exited = `reviewer failed — log: ${log_path}`
+
+	if (!api_auth.is_auth_failed_transcript(stamp_file.read_stamp_text(log_path))) return exited
+
+	return `${api_auth.AUTH_FAILURE_NOTE}: ${exited}`
+}
+
+function current_verdict(): ReturnType<typeof run_ship_review.read_verdict> {
+	return run_ship_review.read_verdict(stamp_file.read_stamp_text(paths().findings))
+}
+
+// **A session that ran and then failed keeps the review it wrote** (joshuafolkken/kit#4562). The
+// findings file is removed before the launch and written as the reviewer's last step, so a readable one
+// is this session's finished review — a late auth failure or a lost broker reply then costs nothing,
+// where a relaunch would review the whole change again. The attest and record phases still judge it.
+function ended_session(failed_note: string): JoshResult {
+	if (current_verdict().kind === run_ship_review.VERDICT.INVALID) {
+		return failure(failed_note, CAUSE.INFRA)
+	}
+
+	note(`${failed_note}\n${KEPT_REVIEW_NOTE}`)
+
+	return { code: SUCCESS_EXIT_CODE, out: '' }
+}
+
+// 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}`, CAUSE.INFRA)
+	}
+
+	if (result.exit_code !== SUCCESS_EXIT_CODE) return ended_session(exited_note(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}`, CAUSE.INFRA)
+	}
+
+	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: '' }
+		: ended_session(`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,
+	)
+}
+
+// A refused attestation — the issue changed after the brief, an update left unread, no attestation —
+// is no finding: the round read what it was briefed on.
+async function attest_phase(): Promise<StepResult> {
+	return tagged(CAUSE.ATTEST, await josh(ATTEST_CHECK))
+}
+
+// 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 tagged(CAUSE.CHECK, result)
+		},
+		async () => await launch_reviewer(opened.brief, prompt_of, issue, round),
+	]
+}
+
+const run_ship_reviewer = {
+	attest_phase,
+	current_verdict,
+	failure,
+	josh,
+	note,
+	paths,
+	reviewed,
+	ROUND_ONE,
+	ROUND_TWO,
+	SUCCESS_EXIT_CODE,
+	tagged,
+	tagged_phase,
+}
+
+export type { Round }
+export { run_ship_reviewer }