@joshuafolkken/kit 1.1471.0 → 1.1514.0

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

@@ -8,7 +8,6 @@ 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 { run_ship, type ShipSection } from './run-ship'
 import { run_ship_detach } from './run-ship-detach'
-import { run_ship_next } from './run-ship-next'
 import { run_ship_pre_detach } from './run-ship-pre-detach'
 import { run_ship_probe } from './run-ship-probe'
 import { run_ship_return } from './run-ship-return'
@@ -295,19 +294,13 @@ async function stopped(
 	step: Step,
 	context: ShipContext,
 ): Promise<ReadonlyArray<ShipSection>> {
-	const conflicts = sections.at(-1)?.conflicts
+	const failed = sections.at(-1)
 
-	await record_stop(args, step.stage, conflicts)
+	await record_stop(args, step.stage, failed?.conflicts)
 
 	if (run_ship_detach.is_supervised()) {
-		const resume = run_ship_next.resume_of(args)
-
 		record(context.target, run_ship_stage.end_attempt)
-		await run_ship_return.return_control(
-			args.number,
-			step.stage,
-			conflicts === undefined ? resume : { ...resume, conflicts },
-		)
+		await run_ship_return.hand_back(args, step.stage, failed)
 	}
 
 	return sections
@@ -381,8 +374,8 @@ function should_detach(args: ShipArguments): boolean {
 
 // The preflight is deterministic and fast, so it runs here, in the agent's own turn, before the
 // hand-off — a stop it finds is fixed by the same session instead of relaunching one from the
-// supervisor. Only the slow stages go to the supervisor, which re-asks the preflight itself. The type
-// check and the document tests follow it here for the same reason; they are not a stage, so the
+// supervisor. Only the slow stages go to the supervisor, which re-asks the preflight itself. The fast
+// checks (`run-ship-pre-detach.ts`) follow it here for the same reason; they are not a stage, so the
 // supervisor's gate runs them again rather than passing over them.
 async function pre_detach_sections(args: ShipArguments): Promise<ReadonlyArray<ShipSection>> {
 	const preflight = await run_stage(run_ship_steps.PREFLIGHT_STEP, args, await open_context(args))

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

@@ -183,6 +183,14 @@ function current_record(repository: string, number: string): ShipRecord | undefi
 	return record?.launch_id === process.env[LAUNCH_ID_KEY] ? record : undefined
 }
 
+// When the ship for `number` that is still running was launched — `undefined` where none is running or
+// its record carries no launch time. `run-ship-overlap.ts` orders two running ships by it.
+function running_since(repository: string, number: string): number | undefined {
+	const record = read_record(repository, number)
+
+	return record !== undefined && result_of(record) === 'running' ? record.launched_at : undefined
+}
+
 function is_pending(record: ShipRecord | undefined): boolean {
 	return record !== undefined && record.pid === undefined
 }
@@ -362,6 +370,7 @@ const run_ship_detach = {
 	last_launch,
 	log_path,
 	read_log,
+	running_since,
 	supervisor_argv,
 }
 

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

@@ -104,13 +104,21 @@ function conflict_step(conflicts: ReadonlyArray<string>): string {
 	return `Resolve the conflict with origin/main in ${conflicts.join(', ')} (the merge is left in progress: remove the conflict markers in those files), then`
 }
 
+// A prompt that already carries the failed output points at it; only one without has the
+// session read the stopped report first.
+function fix_step(issue: string, stage: Stage, is_excerpted: boolean): string {
+	if (is_excerpted) return `Fix the ${stage} failure shown in the output below`
+
+	return `Read the stopped report with \`${COMMAND.LOG} ${issue}\`, fix the ${stage} failure`
+}
+
 // Two lines' worth: read the stopped report, then the one command that resumes after the fix.
-function next_step(issue: string, stage: Stage, resume: ShipResume): string {
+function next_step(issue: string, stage: Stage, resume: ShipResume, is_excerpted = false): string {
 	const conflicts = resume.conflicts ?? []
 
 	if (conflicts.length > 0) return `${conflict_step(conflicts)} ${AFTER_FIX[stage](resume)}`
 
-	return `Read the stopped report with \`${COMMAND.LOG} ${issue}\`, fix the ${stage} failure, then ${AFTER_FIX[stage](resume)}`
+	return `${fix_step(issue, stage, is_excerpted)}, then ${AFTER_FIX[stage](resume)}`
 }
 
 const run_ship_next = { COMMAND, next_step, quoted, resume_of }

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

@@ -0,0 +1,195 @@
+import { changed_paths } from '#scripts/git/changed-paths'
+import { git_diff_reads } from '#scripts/git/git-diff-reads'
+import { git_spawn } from '#scripts/git/git-spawn'
+import { session_cite } from '#scripts/issue/session-cite'
+import { lane_handoff } from '#scripts/lane/lane-handoff'
+import { lane_ledger, type OverlapRecord } from '#scripts/lane/lane-ledger'
+import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
+import { poll } from '#scripts/lib/poll'
+
+// The wait in front of `josh ship`'s sync (joshuafolkken/kit#3901). `backlog-overlap.ts` keeps lanes
+// apart only on the paths their issue bodies declare, so two lanes that both edit an undeclared file
+// were found out only when the later pull request turned `DIRTY` — after its gate and its CI wait,
+// often as a `conflict` stop its child no longer had the context for.
+//
+// **The later ship waits for the earlier one rather than anything being pushed into a lane.** A lane
+// whose actual change overlaps this one's and whose pull request is already open (its branch pushed,
+// its detached ship still running) is waited on until that ship ends, merged or stopped; the sync that
+// follows then merges a default branch that already holds it, so a conflict surfaces before this
+// lane's gate rather than after its CI. Merging into the other lane's tree instead could not work: a
+// lane mid-gate would have its record moved under it, and a lane still implementing holds the
+// overlapping paths uncommitted, which `main:merge`'s guard refuses.
+//
+// **Only a ship launched before this one is waited on**, so two ships never wait on each other — a
+// re-ship after a stop already has a pushed branch, so "pushed" alone could not order two re-ships in
+// their sync. A ship run in an agent's own turn has no launch record and counts as the latest; equal
+// launch times fall to the lower issue number. The wait is bounded — a ship that hangs never holds
+// another past `MAX_WAIT_ATTEMPTS`, after which the sync goes ahead as it always did.
+
+const WAIT_INTERVAL_MS = 30_000
+const MAX_WAIT_ATTEMPTS = 60
+// Unquoted like `read_changed_paths`, so a non-ASCII path compares equal on both sides.
+const NAME_ONLY_ARGUMENTS = [
+	'-c',
+	'core.quotePath=false',
+	'diff',
+	'--name-only',
+	'--no-relative',
+	'--no-renames',
+]
+
+interface OverlapOptions {
+	sleeper?: (duration_ms: number) => Promise<void>
+	ledger?: string
+}
+
+interface Overlap {
+	lanes: ReadonlyArray<LaneInfo>
+	paths: ReadonlyArray<string>
+}
+
+function to_paths(raw: string): Array<string> {
+	return changed_paths.to_paths(raw)
+}
+
+async function has_upstream(directory: string): Promise<boolean> {
+	try {
+		await git_spawn.read(['-C', directory, 'rev-parse', '--verify', '--quiet', '@{upstream}'])
+
+		return true
+	} catch {
+		return false
+	}
+}
+
+// A lane's change as its pushed branch carries it: everything its commits changed since it left the
+// default branch. Read in its own tree, so the other lane's uncommitted edits — not yet on its pull
+// request — are not counted.
+async function lane_paths(directory: string): Promise<ReadonlyArray<string>> {
+	const base = await git_diff_reads.default_branch_reference()
+
+	try {
+		return to_paths(
+			await git_spawn.read(['-C', directory, ...NAME_ONLY_ARGUMENTS, `${base}...HEAD`, '--']),
+		)
+	} catch {
+		return []
+	}
+}
+
+interface Launch {
+	issue: string
+	since: number
+}
+
+function own_launch(issue: string): Launch {
+	const since = lane_handoff.ship_running_since(issue, process.cwd())
+
+	return { issue, since: since ?? Infinity }
+}
+
+function is_launched_before(lane: LaneInfo, own: Launch): boolean {
+	const since = lane_handoff.ship_running_since(lane.issue, lane.directory)
+
+	if (since === undefined) return false
+
+	return since < own.since || (since === own.since && Number(lane.issue) < Number(own.issue))
+}
+
+async function is_open_ship(lane: LaneInfo, own: Launch): Promise<boolean> {
+	if (!is_launched_before(lane, own)) return false
+
+	return await has_upstream(lane.directory)
+}
+
+async function shared_paths(
+	lane: LaneInfo,
+	launch: Launch,
+	own: ReadonlySet<string>,
+): Promise<Array<string>> {
+	if (!(await is_open_ship(lane, launch))) return []
+
+	const paths = await lane_paths(lane.directory)
+
+	return paths.filter((file_path) => own.has(file_path))
+}
+
+async function other_lanes(issue: string): Promise<ReadonlyArray<LaneInfo>> {
+	const lanes = await lane_registry.list_lanes()
+
+	return lanes.filter((lane) => lane.issue !== issue && !lane.is_stranded)
+}
+
+// Every other lane whose open pull request, shipped before this one, touches a path this lane changed,
+// with the shared paths.
+async function find_overlap(issue: string): Promise<Overlap> {
+	const own = new Set(await changed_paths.read_changed_paths(false))
+	const launch = own_launch(issue)
+	const others = await other_lanes(issue)
+	const shared = await Promise.all(
+		others.map(async (lane) => await shared_paths(lane, launch, own)),
+	)
+
+	return {
+		lanes: others.filter((_lane, index) => (shared[index] ?? []).length > 0),
+		paths: [...new Set(shared.flat())].toSorted((left, right) => left.localeCompare(right)),
+	}
+}
+
+async function read_overlap(issue: string): Promise<Overlap> {
+	try {
+		return await find_overlap(issue)
+	} catch {
+		return { lanes: [], paths: [] }
+	}
+}
+
+function is_settled(lanes: ReadonlyArray<LaneInfo>): boolean {
+	return lanes.every((lane) => !lane_handoff.is_ship_running(lane.issue, lane.directory))
+}
+
+async function wait_for(lanes: ReadonlyArray<LaneInfo>, options: OverlapOptions): Promise<boolean> {
+	return await poll.poll_until(async () => is_settled(lanes), {
+		attempts: MAX_WAIT_ATTEMPTS,
+		interval_ms: WAIT_INTERVAL_MS,
+		sleeper: options.sleeper ?? poll.sleep,
+	})
+}
+
+// Waits out every overlapping open ship and records the decision, returning what was recorded; a lane
+// that overlaps nothing returns `undefined` at once and writes nothing. Best-effort: an overlap that
+// could not be read is no overlap, so the sync is never blocked by the check that only exists to make
+// it land cleaner.
+async function await_overlap(
+	issue: string,
+	options: OverlapOptions = {},
+): Promise<OverlapRecord | undefined> {
+	const overlap = await read_overlap(issue)
+
+	if (overlap.lanes.length === 0) return undefined
+
+	const started = Date.now()
+	const is_cleared = await wait_for(overlap.lanes, options)
+	const lanes = overlap.lanes.map((lane) => Number(lane.issue))
+	const waited_ms = Date.now() - started
+	const record = { issue: Number(issue), lanes, paths: [...overlap.paths], waited_ms, is_cleared }
+
+	await lane_ledger.record_overlap(record, options.ledger)
+
+	return record
+}
+
+// The line the sync stage prints for a recorded wait, or `''` where nothing overlapped.
+function note(record: OverlapRecord | undefined): string {
+	if (record === undefined) return ''
+
+	const lanes = record.lanes.map((lane) => session_cite.issue(lane)).join(', ')
+	const outcome = record.is_cleared ? 'waited for' : 'gave up waiting for'
+
+	return `${outcome} ${lanes}, whose open pull requests also change: ${record.paths.join(', ')}`
+}
+
+const run_ship_overlap = { MAX_WAIT_ATTEMPTS, await_overlap, note }
+
+export type { OverlapOptions }
+export { run_ship_overlap }

package/scripts/run/ship/run-ship-pre-detach.ts

@@ -6,14 +6,19 @@ import type { JoshResult } from '#scripts/josh/josh-run'
 import { buffered_process, type BufferedProcessResult } from '#scripts/lib/buffered-process'
 
 // The fast checks a detached `josh ship` runs in the agent's own turn, after the preflight and before
-// the hand-off: a type error in a file the related-only checks never touched, or a document test (a
-// SKILL.md pointer, a byte budget, the command list) that only the full suite runs, would otherwise
-// first surface after the detach and cost a relaunched session. These two answer in seconds, so the
-// same session fixes what they find and ships again. **Nothing moves out of the gate**: the
-// supervised gate stage still runs every check, these included.
+// the hand-off: a type error in a file the related-only checks never touched, an export nothing reads,
+// an unknown word, or a guard test (a SKILL.md pointer, a byte budget, the command list, a source with
+// no colocated test, a bare issue citation) that only the full suite runs, would otherwise first
+// surface after the detach and cost a relaunched session. They answer in seconds, so the same session
+// fixes what they find and ships again. **Nothing moves out of the gate**: the supervised gate stage
+// still runs every check, these included.
 //
-// The test targets are the directories such failures land in. A consumer has none of them, so only
-// the ones present run, and a consumer meets the type check alone.
+// joshuafolkken/kit#3924: nine of ten ship gate stops were `exports:unused`, `cspell:dot` or a
+// repository-wide guard test failing on the child's own code — none a check `test:related` selects,
+// since a guard test imports no changed file.
+//
+// The test targets are where such failures land. A consumer has none of them, so only the ones
+// present run, and a consumer meets the static checks alone.
 //
 // In kit the metrics ratchet's totals join them: a feature grows a total almost every time, and here
 // the session that grew the total writes the reason itself rather than a relaunched one. The
@@ -25,24 +30,31 @@ const FAILURE_EXIT_CODE = 1
 const SECTION_SEPARATOR = '\n\n'
 const PASSED = 'pre-detach checks passed'
 const METRICS_TOTALS_COMMAND: ReadonlyArray<string> = ['josh', 'metrics', '--totals-only']
-const DOCUMENT_TEST_TARGETS: ReadonlyArray<string> = [
+const STATIC_CHECKS: ReadonlyArray<ReadonlyArray<string>> = [
+	['josh', 'exports:unused'],
+	['josh', 'cspell:dot'],
+]
+const GUARD_TEST_TARGETS: ReadonlyArray<string> = [
 	'scripts/document',
 	'scripts/claude',
 	'scripts/rules',
 	'scripts/josh/josh-command-map.test.ts',
+	'scripts/issue/session-cite-scan.test.ts',
+	'scripts/test/untested-sources.test.ts',
+	'scripts/test/pure-files.test.ts',
 ]
 // A present directory need not hold a test the project's Vitest includes — a consumer's own
 // `scripts/claude` of shell helpers, say — and a filter that matches nothing would stop every ship.
-const DOCUMENT_TEST_COMMAND: ReadonlyArray<string> = ['josh', 'test:unit', '--passWithNoTests']
+const GUARD_TEST_COMMAND: ReadonlyArray<string> = ['josh', 'test:unit', '--passWithNoTests']
 
 function present_targets(directory: string): ReadonlyArray<string> {
-	return DOCUMENT_TEST_TARGETS.filter((target) => existsSync(path.join(directory, target)))
+	return GUARD_TEST_TARGETS.filter((target) => existsSync(path.join(directory, target)))
 }
 
-function document_tests(directory: string): Array<ReadonlyArray<string>> {
+function guard_tests(directory: string): Array<ReadonlyArray<string>> {
 	const targets = present_targets(directory)
 
-	return targets.length === 0 ? [] : [[...DOCUMENT_TEST_COMMAND, ...targets]]
+	return targets.length === 0 ? [] : [[...GUARD_TEST_COMMAND, ...targets]]
 }
 
 // The same kit-only rule as the gate's `is_kit_only` step: a consumer's kit has no `josh metrics`.
@@ -53,7 +65,7 @@ function kit_only(directory: string): Array<ReadonlyArray<string>> {
 async function command_lists(directory: string): Promise<Array<ReadonlyArray<string>>> {
 	const type_check = await type_check_step.resolve_type_check_args(directory)
 
-	return [type_check, ...document_tests(directory), ...kit_only(directory)]
+	return [type_check, ...STATIC_CHECKS, ...guard_tests(directory), ...kit_only(directory)]
 }
 
 async function run_in(
@@ -63,7 +75,7 @@ async function run_in(
 	return await buffered_process.run_buffered_process(list, { cwd: directory })
 }
 
-// Both run at once, buffered, and every failure is reported, so one ship shows all there is to fix.
+// All run at once, buffered, and every failure is reported, so one ship shows all there is to fix.
 async function checks(directory: string = process.cwd()): Promise<JoshResult> {
 	const lists = await command_lists(directory)
 	const results = await Promise.all(lists.map(async (list) => await run_in(directory, list)))
@@ -77,6 +89,12 @@ async function checks(directory: string = process.cwd()): Promise<JoshResult> {
 	}
 }
 
-const run_ship_pre_detach = { DOCUMENT_TEST_TARGETS, METRICS_TOTALS_COMMAND, PASSED, checks }
+const run_ship_pre_detach = {
+	GUARD_TEST_TARGETS,
+	METRICS_TOTALS_COMMAND,
+	PASSED,
+	STATIC_CHECKS,
+	checks,
+}
 
 export { run_ship_pre_detach }

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

@@ -3,9 +3,11 @@ import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { git_pr } from '#scripts/gh/git-pr'
 import { changed_paths } from '#scripts/git/changed-paths'
 import { git_branch } from '#scripts/git/git-branch'
+import { git_issue } from '#scripts/git/git-issue'
 import { git_preflight } from '#scripts/git/git-preflight'
 import type { JoshResult } from '#scripts/josh/josh-run'
 import { error_text } from '#scripts/lib/error-message'
+import { acceptance_map_check } from '#scripts/review/acceptance-map-check'
 import { live_evidence } from '#scripts/review/live-evidence'
 import { run_ship_lock } from './run-ship-lock'
 import { run_ship_scoped } from './run-ship-scoped'
@@ -22,6 +24,7 @@ import { run_ship_scoped } from './run-ship-scoped'
 
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
+const UNREADABLE = Symbol('unreadable body')
 const EVIDENCE_PROBLEM = `This change touches runtime code, but the PR body has no ${live_evidence.EVIDENCE_HEADING} section: run the acceptance criteria for real and pass the body with --body-file <path>. Write it ${live_evidence.EVIDENCE_FORMAT}`
 const EVIDENCE_PENDING = `This change touches runtime code and no PR is open yet: write the ${live_evidence.EVIDENCE_HEADING} section to a file and hand it to josh ship with --body-file <path>, or the ship refuses. Write it ${live_evidence.EVIDENCE_FORMAT}`
 
@@ -71,16 +74,39 @@ async function caught(problems: Promise<Array<string>>): Promise<Array<string>>
 	}
 }
 
+async function readable_body(
+	body_path: string | undefined,
+): Promise<string | undefined | typeof UNREADABLE> {
+	try {
+		return await body_text(body_path)
+	} catch {
+		return UNREADABLE
+	}
+}
+
+// `followup`'s acceptance-map refusal, asked of the body this ship will deliver. A branch with no issue
+// number is `git_preflight`'s problem to name, and an unreadable body the evidence side's.
+async function acceptance_problems(body_path: string | undefined): Promise<Array<string>> {
+	const issue = git_issue.branch_number(await git_branch.current())
+	const body = await readable_body(body_path)
+
+	if (issue === undefined || body === UNREADABLE) return []
+	const problem = await acceptance_map_check.body_refusal(issue, body)
+
+	return problem === undefined ? [] : [problem]
+}
+
 // The lock file is asked here too, so a drift stops the ship before the gate
 // rather than being rewritten by the pre-push hook's install under the push.
 async function asked_problems(request: PreflightRequest): Promise<Array<string>> {
-	const [preflight, evidence, lock] = await Promise.all([
+	const [preflight, evidence, acceptance, lock] = await Promise.all([
 		caught(git_preflight.problems_of({ cli_input: request.title, will_open_pr: true })),
 		caught(evidence_problems(request.body_path)),
+		caught(acceptance_problems(request.body_path)),
 		caught(run_ship_lock.lock_problems()),
 	])
 
-	return [...preflight, ...evidence, ...lock]
+	return [...preflight, ...evidence, ...acceptance, ...lock]
 }
 
 async function stage(request: PreflightRequest): Promise<JoshResult> {

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

@@ -6,8 +6,11 @@ import { lane_relaunch } from '#scripts/lane/lane-relaunch'
 import { lane_session_broker } from '#scripts/lane/lane-session-broker'
 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 { ShipResume } from './run-ship-next'
+import type { ShipSection } from './run-ship'
+import { run_ship_next, type ShipResume } from './run-ship-next'
 import { run_ship_stage, type Stage } from './run-ship-stage'
+import type { ShipArguments } from './run-ship-steps'
+import { run_ship_stop_context } from './run-ship-stop-context'
 import { run_ship_stop_text } from './run-ship-stop-text'
 
 // How a detached `josh ship` supervisor hands a stopped stage back. The agent
@@ -66,19 +69,26 @@ function relaunched(lane: LaneInfo, stop: ShipStop): ReturnOutcome {
 // 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> {
-	if (await lane_session_broker.request(lane.directory, lane.issue, { kind: 'relaunch', stop })) {
-		return 'relaunched'
-	}
+	const answer = await lane_session_broker.request(lane.directory, lane.issue, {
+		kind: 'relaunch',
+		stop,
+	})
 
-	note('the lane child could not be relaunched: the lane broker did not start it')
+	if (answer.is_success) return 'relaunched'
+
+	note(
+		`the lane child could not be relaunched: the lane broker did not start it — ${answer.reason}`,
+	)
 
 	return 'recorded'
 }
 
+// `output` is the failed stage's own output: the relaunched child's prompt carries its tail.
 async function return_control(
 	issue: string,
 	stage: Stage,
 	resume: ShipResume,
+	output: string,
 ): Promise<ReturnOutcome> {
 	await run_event_stream_emit.emit(
 		run_event_stream.EVENT_KIND.SHIP_STOP,
@@ -89,14 +99,28 @@ async function return_control(
 
 	if (lane === undefined) return 'recorded'
 
-	const stop = { stage, ...resume }
+	const stop = { stage, ...resume, context: await run_ship_stop_context.build(issue, output) }
 
 	return lane_session_broker.is_serving(lane.directory, issue)
 		? await brokered(lane, stop)
 		: relaunched(lane, stop)
 }
 
-const run_ship_return = { return_control }
+// 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.
+async function hand_back(
+	args: ShipArguments,
+	stage: Stage,
+	failed: Pick<ShipSection, 'body' | 'conflicts'> | undefined,
+): Promise<ReturnOutcome> {
+	const resume = run_ship_next.resume_of(args)
+	const conflicts = failed?.conflicts
+	const stopped = conflicts === undefined ? resume : { ...resume, conflicts }
+
+	return await return_control(args.number, stage, stopped, failed?.body ?? '')
+}
+
+const run_ship_return = { hand_back, return_control }
 
 export type { ReturnOutcome }
 export { run_ship_return }

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

@@ -77,15 +77,18 @@ 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.
+// 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}`)
@@ -110,19 +113,18 @@ async function run_session(
 	issue: string,
 	round: Round,
 ): Promise<JoshResult> {
-	const built = agent_argv.resolve_in(prompt, agent_role_profile.REVIEWER, PROJECT_ROOT)
+	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)
+		return await run_direct_session(built.argv, built.profile, log_path, round)
 	}
 
-	const is_success = await lane_session_broker.request(PROJECT_ROOT, issue, {
-		kind: 'review',
-		round,
-	})
+	const answer = await lane_session_broker.request(PROJECT_ROOT, issue, { kind: 'review', round })
 
-	return is_success ? { code: SUCCESS_EXIT_CODE, out: '' } : failure('isolated reviewer failed')
+	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

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

@@ -65,7 +65,7 @@ const COMMIT_STEPS: ReadonlyArray<Step> = [
 	{
 		stage: STAGE.SYNC,
 		header: run_ship.SYNC_HEADER,
-		run: async () => await run_ship_sync.sync_stage(),
+		run: async (args) => await run_ship_sync.sync_stage(args.number),
 	},
 	{
 		stage: STAGE.GATE,