@joshuafolkken/kit 1.1514.0 → 1.2114.0

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

@@ -1,5 +1,8 @@
 import { issue_cite } from '#scripts/issue/issue-cite'
+import { review_attest, type ReviewSlot } from '#scripts/review/review-attest'
 import { review_finding_ledger } from '#scripts/review/review-finding-ledger'
+import { review_finding_text } from '#scripts/review/review-finding-text'
+import { review_prior_findings } from '#scripts/review/review-prior-findings'
 import { review_record_cli } from '#scripts/review/review-record-cli'
 
 // The pure half of `josh ship --review`: the one-line prompts the supervised reviewers are launched
@@ -23,12 +26,15 @@ const LINE_SEPARATOR = /\r?\n/u
 const HIGH = 'high'
 const MEDIUM = 'medium'
 const FIXED_PREFIX = 'fixed '
-// 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
+const KIND_FIELDS = 2
+// `findings_path` is set only for a lane whose josh predates `review:submit`
+// (`lane-session-action.ts`).
+type PromptOf = (
+	brief_path: string,
+	slot: ReviewSlot,
+	issue: string,
+	findings_path?: string,
+) => string
 
 const VERDICT = {
 	CLEAN: 'clean',
@@ -57,30 +63,83 @@ 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'
 const CLEAN_NOTE = 'review clean or Low-only — recorded; shipping on.'
 const FIXED_NOTE =
 	'review fixes applied in place — recorded; the gate re-runs on the fixed tree and round 2 follows the commit.'
-const BLOCKING_NOTE =
-	'review found High/Medium it did not fix — recorded; fix them, then take the round-2 route (`chain-rule.md`).'
+// Every stop that hands findings back for a fix: a fix of only the cited line left the same pattern
+// beside it for the next round to stop on again (joshuafolkken/kit#4673).
+const SWEEP_INSTRUCTION = [
+	'Before fixing, sweep each finding for its other sites — the same file, the callers of the same',
+	'function and a grep of the pattern — fix every site in one pass, and list each range searched on its',
+	'own line in the Issue fix comment.',
+].join(' ')
+const BLOCKING_NOTE = `review found High/Medium it did not fix — recorded. ${SWEEP_INSTRUCTION} Then take the round-2 route (\`chain-rule.md\`).`
 const UNVERIFIED_OUTCOME: RoundOutcome = {
 	is_passing: false,
-	note: 'review fixes did not pass the scoped checks — recorded as unfixed; fix them, then take the round-2 route (`chain-rule.md`).',
+	note: `review fixes did not pass the scoped checks — recorded as unfixed. ${SWEEP_INSTRUCTION} Then take the round-2 route (\`chain-rule.md\`).`,
 }
+// The findings line is all a stopped ship hands the lane, so the other sites the rubric asks the
+// reviewer to cite ride on it rather than in its prose report (joshuafolkken/kit#4673).
+const OTHER_SITES_CLAUSE = '"other sites: <file>:<line>, …" for each other site of the same pattern'
 const ROUND_TWO_CLEAN_NOTE = 'round 2 clean or Low-only — recorded; shipping on.'
-const ROUND_TWO_BLOCKING_NOTE =
-	'round 2 found High/Medium or edited the tree — recorded; round 2 is final: fix, push and gate it, then run followup (`chain-rule.md` step 4).'
+const SUBMIT_COMMAND = 'pnpm josh review:submit'
+const ROUND_TWO_BLOCKING_NOTE = `round 2 found High/Medium or edited the tree — recorded; round 2 is final. ${SWEEP_INSTRUCTION} Then push and gate it, and run followup (\`chain-rule.md\` step 4).`
+
+// **The reviewer hands its findings to a command, never to a path it copies** (joshuafolkken/kit#4799):
+// a reviewer that copied the findings path matched the `josh-review-*` files beside it and dropped
+// `ship-`, so the supervisor never read a review it had finished. `review:submit` knows the slot's path.
+function submit_command(slot: ReviewSlot): string {
+	return slot === review_attest.REVIEW_SLOT.CODE
+		? SUBMIT_COMMAND
+		: `${SUBMIT_COMMAND} --interaction`
+}
+
+// **A lane whose josh predates `review:submit` is handed the path**: the supervisor reloads onto main
+// at its pass boundary (`run-wake-code.ts`), so it meets lanes branched before the command existed.
+function sink_clauses(
+	slot: ReviewSlot,
+	findings_path: string | undefined,
+): readonly [string, string] {
+	if (findings_path !== undefined) {
+		return [
+			`Then write every finding to ${findings_path},`,
+			'and an empty file when there is none.',
+		]
+	}
+
+	return [
+		`Then pipe every finding on stdin to \`${submit_command(slot)}\` — never write a findings file yourself —`,
+		'or run it with `--none` and no stdin when there is none; if it refuses a line, fix that line and run it again.',
+	]
+}
 
-function findings_instruction(findings_path: string, fixed_clause: string): string {
+function findings_instruction(
+	slot: ReviewSlot,
+	fixed_clause: string,
+	findings_path: string | undefined,
+): string {
 	const categories = review_finding_ledger.CATEGORIES.join(', ')
+	const [opening, closing] = sink_clauses(slot, findings_path)
 
 	return [
-		`Then write every finding to ${findings_path}, one per line as`,
-		`<category>:<severity>:<file>[:<line>]${DESCRIPTION_SEPARATOR}<one sentence: what is wrong and why>`,
+		opening,
+		'one per line as',
+		`<category>:<severity>:<file>[:<line>]${review_finding_text.DESCRIPTION_SEPARATOR}<one sentence: what is wrong and why>`,
 		`(category one of ${categories}; severity high, medium or low)${fixed_clause},`,
-		'and an empty file when there is none.',
+		`a high or medium line ending with ${OTHER_SITES_CLAUSE},`,
+		closing,
 	].join(' ')
 }
 
@@ -94,43 +153,99 @@ function issue_read_instruction(issue: string): string {
 	].join(' ')
 }
 
+// **The review runs in this session itself** (joshuafolkken/kit#4715): a reviewer that invoked the
+// `/code-review` skill forked a second agent that read the same diff and brief again. The session is
+// launched without the `Skill` and `Agent` tools (`claude-agent-argv.ts`), and the prompt says so.
+const IN_SESSION_CLAUSE =
+	'Review it yourself in this session — you carry no Skill or Agent tool, so never launch a second reviewer.'
+
+function round_one_opening(brief_path: string): string {
+	return [
+		`Review this checkout as a /code-review: read the review brief at ${brief_path} and follow it exactly —`,
+		'the level on its first line, the rubric it names, the checkout it pins and its review:attest step.',
+		IN_SESSION_CLAUSE,
+	].join(' ')
+}
+
 // One line, because `detached_launch` refuses an argument carrying a control character: the multi-line
 // brief travels by path, never inline.
-function reviewer_prompt(brief_path: string, findings_path: string, issue: string): string {
+function reviewer_prompt(
+	brief_path: string,
+	slot: ReviewSlot,
+	issue: string,
+	findings_path?: string,
+): string {
 	return [
-		`Run a /code-review of this checkout: read the review brief at ${brief_path} and follow it exactly —`,
-		'the level on its first line, the rubric it names, the checkout it pins and its review:attest step.',
+		round_one_opening(brief_path),
 		issue_read_instruction(issue),
+		...review_prior_findings.prompt_clauses(issue),
 		'Apply a fix only for a Medium finding whose fix is small and local — a one-function refactor, an',
 		'added test, an added guard; never fix a High or a change that reaches beyond one place, and never',
 		'commit, stage or push. After any fix, run `pnpm josh lint:related && pnpm josh test:related` and',
 		'return only once both are green; revert a fix you cannot get green and report that finding unfixed.',
-		findings_instruction(findings_path, `, prefixing a finding you fixed with "${FIXED_PREFIX}"`),
+		findings_instruction(
+			slot,
+			`, prefixing a finding you fixed with "${FIXED_PREFIX}"`,
+			findings_path,
+		),
 	].join(' ')
 }
 
-// The round-2 verification pass: a fresh session over the round-1 fix delta, reading only.
-function verification_prompt(brief_path: string, findings_path: string, issue: string): string {
+// The round-1 review run beside the code review: it reads only, so the two sessions never fix, verify
+// and revert in the one shared checkout at once; its findings go to the lane's one fix pass.
+function report_prompt(
+	brief_path: string,
+	slot: ReviewSlot,
+	issue: string,
+	findings_path?: string,
+): string {
 	return [
-		`Run a /code-review of this checkout — the round-2 verification pass over the round-1 fixes: read the`,
-		`review brief at ${brief_path} and follow it exactly — the level on its first line, the rubric it`,
-		'names, the checkout it pins and its review:attest step. Do not edit any file.',
+		round_one_opening(brief_path),
+		'Do not edit any file: the code review running beside this one fixes in this checkout.',
 		issue_read_instruction(issue),
-		findings_instruction(findings_path, ''),
+		...review_prior_findings.prompt_clauses(issue),
+		findings_instruction(slot, '', findings_path),
 	].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)
+// **One reviewer edits the checkout** (joshuafolkken/kit#4672): a slot reviewed beside the code slot
+// reads only, and a slot reviewed alone takes the round's own prompt.
+function slot_prompt(
+	round_prompt: PromptOf,
+	slot: ReviewSlot,
+	slots: ReadonlyArray<ReviewSlot>,
+): PromptOf {
+	if (slot === review_attest.REVIEW_SLOT.CODE || slots.length === 1) return round_prompt
 
-	return (end === -1 ? unmarked : unmarked.slice(0, end)).trim()
+	return report_prompt
+}
+
+// The round-2 verification pass: a fresh session over the round-1 fix delta, reading only.
+function verification_prompt(
+	brief_path: string,
+	slot: ReviewSlot,
+	issue: string,
+	findings_path?: string,
+): string {
+	return [
+		`Review this checkout as a /code-review — the round-2 verification pass over the round-1 fixes: read the`,
+		`review brief at ${brief_path} and follow it exactly — the level on its first line, the rubric it`,
+		'names, the checkout it pins and its review:attest step. Do not edit any file.',
+		IN_SESSION_CLAUSE,
+		issue_read_instruction(issue),
+		...review_prior_findings.prompt_clauses(issue),
+		findings_instruction(slot, '', findings_path),
+	].join(' ')
 }
 
+// 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 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 }
+	const unmarked = is_fixed ? line.slice(FIXED_PREFIX.length) : line
+
+	return { ...review_finding_text.split_description(unmarked), is_fixed, line }
 }
 
 function spec_findings(text: string): ReadonlyArray<Finding> {
@@ -153,6 +268,55 @@ 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: review_finding_text.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))
+}
+
+// The findings a passing round 1 fixed in place — the stop log's only chance to see them, since no stop
+// follows (joshuafolkken/kit#4780); none for any other round.
+function passing_fixes(verdict: ScoredVerdict, outcome: RoundOutcome): ReadonlyArray<StopFinding> {
+	if (!outcome.is_passing || verdict.kind !== VERDICT.FIXED) return []
+
+	return blocking_details(verdict.report.join('\n'))
+}
+
 function scored_kind(findings: ReadonlyArray<Finding>): ScoredVerdict['kind'] {
 	if (findings.some((finding) => is_blocking(finding))) return VERDICT.BLOCKING
 
@@ -160,9 +324,10 @@ function scored_kind(findings: ReadonlyArray<Finding>): ScoredVerdict['kind'] {
 }
 
 // Absent means the reviewer never finished; a line outside the grammar means its verdict cannot be
-// recorded — both stop the ship rather than read as clean. The specs are recorded without the `fixed`
-// mark: a fixed finding was still a finding of that round. The report keeps each line whole — mark and
-// description — for the stage output a resumed lane child reads.
+// recorded — both stop the ship rather than read as clean. A fixed finding is recorded with its
+// `fixed` mark, the disposition `review:record` keeps in the ledger and `review:round2` reads round 1's
+// closure from (joshuafolkken/kit#5286). The report keeps each line whole — mark and description — for
+// the stage output a resumed lane child reads.
 function read_verdict(text: string | undefined): ReviewVerdict {
 	if (text === undefined) return { kind: VERDICT.INVALID, note: MISSING_NOTE }
 
@@ -175,11 +340,23 @@ function read_verdict(text: string | undefined): ReviewVerdict {
 
 	return {
 		kind: scored_kind(findings),
-		specs: findings.map((finding) => finding.spec),
+		specs: findings.map((finding) =>
+			finding.is_fixed ? `${FIXED_PREFIX}${finding.spec}` : finding.spec,
+		),
 		report: findings.map((finding) => finding.line),
 	}
 }
 
+// The specs `review:record` is given: a stopped round's `fixed` marks are dropped, since a fix the scoped
+// pair turned down, or one beside a finding still blocking, has not closed what it marks.
+function recorded_specs(verdict: ScoredVerdict, outcome: RoundOutcome): ReadonlyArray<string> {
+	if (outcome.is_passing) return verdict.specs
+
+	return verdict.specs.map((spec) =>
+		spec.startsWith(FIXED_PREFIX) ? spec.slice(FIXED_PREFIX.length) : spec,
+	)
+}
+
 // Round 1 passes clean or with every blocking finding fixed in place; round 2 follows the commit.
 function round_one_outcome(verdict: ScoredVerdict): RoundOutcome {
 	if (verdict.kind === VERDICT.BLOCKING) return { is_passing: false, note: BLOCKING_NOTE }
@@ -214,16 +391,26 @@ function round_two_outcome(verdict: ScoredVerdict): RoundOutcome {
 
 const run_ship_review = {
 	FIXED_PREFIX,
+	OTHER_SITES_CLAUSE,
+	SWEEP_INSTRUCTION,
 	UNVERIFIED_OUTCOME,
 	VERDICT,
+	blocking_details,
+	blocking_kinds,
 	has_fixes,
 	is_clean_round_one,
+	passing_fixes,
 	read_verdict,
+	recorded_specs,
+	report_prompt,
 	reviewer_prompt,
+	round_one_opening,
 	round_one_outcome,
 	round_two_outcome,
+	slot_prompt,
+	submit_command,
 	verification_prompt,
 }
 
-export type { ReviewVerdict, RoundOutcome, ScoredVerdict }
+export type { PromptOf, ReviewVerdict, RoundOutcome, ScoredVerdict, StopFinding }
 export { run_ship_review }

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

@@ -0,0 +1,303 @@
+import { agent_argv, type AgentArgv, type AgentArgvResult } 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 { review_attest, type ReviewSlot } from '#scripts/review/review-attest'
+import { detached_launch } from '#scripts/run/detached-launch'
+import { run_ship_brokered_review } from './run-ship-brokered-review'
+import { run_ship_review, type PromptOf } 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.'
+const MISSING_FINDINGS_NOTE = 'the reviewer submitted no findings; nothing is at the slot path:'
+type Round = '1' | '2'
+
+const ROUND_ONE: Round = '1'
+const ROUND_TWO: Round = '2'
+
+interface SlotOpen {
+	open: ReadonlyArray<string>
+	slot: ReviewSlot
+}
+
+interface Briefed {
+	brief: string
+	slot: ReviewSlot
+}
+
+const { CAUSE } = run_ship_stop_cause
+const { CODE } = review_attest.REVIEW_SLOT
+
+// **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(slot?: ReviewSlot): { brief: string; findings: string; log: string } {
+	return lane_session_broker.review_paths(PROJECT_ROOT, slot)
+}
+
+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(slot?: ReviewSlot): ReturnType<typeof run_ship_review.read_verdict> {
+	return run_ship_review.read_verdict(stamp_file.read_stamp_text(paths(slot).findings))
+}
+
+// **A session that ended with no findings file names the slot's path** (joshuafolkken/kit#4774) — the
+// one `review:submit` writes, or the one a lane predating it was told to write: a reviewer that never
+// submitted otherwise stops the round later, on a join or a record that never says the file is missing.
+function missing_findings(slots: ReadonlyArray<ReviewSlot>): string | undefined {
+	const missing = slots
+		.map((slot) => paths(slot).findings)
+		.filter((findings) => stamp_file.read_stamp_text(findings) === undefined)
+
+	return missing.length === 0 ? undefined : `${MISSING_FINDINGS_NOTE} ${missing.join(', ')}`
+}
+
+function finished_session(slots: ReadonlyArray<ReviewSlot>): JoshResult {
+	const missing = missing_findings(slots)
+
+	return missing === undefined
+		? { code: SUCCESS_EXIT_CODE, out: '' }
+		: failure(missing, CAUSE.INFRA)
+}
+
+// **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.
+// A broker answers for every slot it ran at once, so each slot's file must be readable.
+function ended_session(failed_note: string, slots: ReadonlyArray<ReviewSlot> = [CODE]): JoshResult {
+	if (slots.some((slot) => current_verdict(slot).kind === run_ship_review.VERDICT.INVALID)) {
+		const missing = missing_findings(slots)
+
+		return failure(missing === undefined ? failed_note : `${failed_note}\n${missing}`, 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. A failed session is
+// judged on its own slot's findings, not on a sibling's still being written.
+async function run_direct_session(
+	argv: AgentArgv,
+	profile: AgentProfile,
+	slot: ReviewSlot,
+	round: Round,
+): Promise<JoshResult> {
+	const log_path = paths(slot).log
+	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), [slot])
+
+	return finished_session([slot])
+}
+
+// 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)
+}
+
+interface SlotSession {
+	slot: ReviewSlot
+	built: AgentArgvResult
+}
+
+function session_for(
+	prompt_of: PromptOf,
+	issue: string,
+	round: Round,
+	slots: { slot: ReviewSlot; all: ReadonlyArray<ReviewSlot> },
+): SlotSession {
+	const { slot, all } = slots
+	const prompt = run_ship_review.slot_prompt(prompt_of, slot, all)(paths(slot).brief, slot, issue)
+
+	return { slot, built: agent_argv.review_in(prompt, Number(round), PROJECT_ROOT) }
+}
+
+async function run_slot(session: SlotSession, round: Round): Promise<JoshResult> {
+	const { built, slot } = session
+
+	if (built.kind === 'rejected') {
+		return failure(`reviewer profile rejected: ${built.note}`, CAUSE.INFRA)
+	}
+
+	return await run_direct_session(built.argv, built.profile, slot, round)
+}
+
+async function run_brokered(
+	issue: string,
+	round: Round,
+	slots: ReadonlyArray<ReviewSlot>,
+): Promise<JoshResult> {
+	const answer = await run_ship_brokered_review.request(PROJECT_ROOT, issue, round, slots)
+
+	return answer.is_success
+		? finished_session(slots)
+		: ended_session(`isolated reviewer failed: ${answer.reason}`, slots)
+}
+
+// **The slots' reviewers run side by side** (joshuafolkken/kit#4672), and the first failure among
+// them is the result — each slot is launched through the same path a single review takes.
+async function run_sessions(
+	prompt_of: PromptOf,
+	issue: string,
+	round: Round,
+	slots: ReadonlyArray<ReviewSlot>,
+): Promise<JoshResult> {
+	const sessions = slots.map((slot) => session_for(prompt_of, issue, round, { slot, all: slots }))
+	const [first] = sessions
+
+	if (first?.built.kind === 'argv' && is_brokered(first.built.profile, issue)) {
+		return await run_brokered(issue, round, slots)
+	}
+
+	const results = await Promise.all(sessions.map(async (session) => await run_slot(session, round)))
+
+	return (
+		results.find((result) => result.code !== SUCCESS_EXIT_CODE) ?? {
+			code: SUCCESS_EXIT_CODE,
+			out: '',
+		}
+	)
+}
+
+// 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_reviewers(
+	briefs: ReadonlyArray<Briefed>,
+	prompt_of: PromptOf,
+	issue: string,
+	round: Round,
+): Promise<JoshResult> {
+	for (const { brief, slot } of briefs) {
+		const target = paths(slot)
+
+		stamp_file.write_text_stamp(target.brief, brief)
+		stamp_file.remove_stamp(target.findings)
+	}
+
+	return await run_sessions(
+		prompt_of,
+		issue,
+		round,
+		briefs.map(({ slot }) => slot),
+	)
+}
+
+// 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. `review:attest --check` asks every slot.
+async function attest_phase(): Promise<StepResult> {
+	return tagged(CAUSE.ATTEST, await josh(ATTEST_CHECK))
+}
+
+// Each slot's brief-minting command in turn, then their reviewers side by side, each handed what its
+// command printed. The slots are the ones asked for, not the ones whose command has run so far.
+function reviewed_together(
+	opens: ReadonlyArray<SlotOpen>,
+	prompt_of: PromptOf,
+	issue: string,
+	round: Round,
+): ReadonlyArray<Phase> {
+	const printed = new Map<ReviewSlot, string>()
+
+	function briefs(): ReadonlyArray<Briefed> {
+		return opens.map(({ slot }) => ({ brief: printed.get(slot) ?? '', slot }))
+	}
+
+	return [
+		...opens.map(({ open, slot }) => async () => {
+			const result = await josh(open)
+
+			printed.set(slot, result.out)
+
+			return tagged(CAUSE.CHECK, result)
+		}),
+		async () => await launch_reviewers(briefs(), prompt_of, issue, round),
+	]
+}
+
+// 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> {
+	return reviewed_together([{ open, slot: CODE }], prompt_of, issue, round)
+}
+
+const run_ship_reviewer = {
+	attest_phase,
+	current_verdict,
+	failure,
+	josh,
+	note,
+	paths,
+	reviewed,
+	reviewed_together,
+	ROUND_ONE,
+	ROUND_TWO,
+	SUCCESS_EXIT_CODE,
+	tagged,
+	tagged_phase,
+}
+
+export type { Round }
+export { run_ship_reviewer }