@joshuafolkken/kit 1.1784.0 → 1.2116.0

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

@@ -1,5 +1,7 @@
 import { setTimeout as sleep } from 'node:timers/promises'
 import { agent_role_profile } from '#scripts/agent/agent-role-profile'
+import { backlog_budget } from '#scripts/backlog/backlog-budget'
+import { issue_cite } from '#scripts/issue/issue-cite'
 import { lane_child_invocation, type ShipStop } from '#scripts/lane/lane-child-invocation'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
 import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
@@ -7,6 +9,7 @@ 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 { run_wake_driver } from '#scripts/run/wake/run-wake-driver'
 import type { ShipSection } from './run-ship'
 import { run_ship_next, type ShipResume } from './run-ship-next'
 import { run_ship_place } from './run-ship-place'
@@ -17,6 +20,7 @@ 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'
+import { run_ship_waiter } from './run-ship-waiter'
 
 // How a detached `josh ship` supervisor hands a stopped stage back. The agent
 // ended when it handed the region over, so a red gate, a High/Medium review, a failed push or red CI has
@@ -30,7 +34,8 @@ 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.
+//    The relaunches are capped: past the cap the issue is parked and a person told instead. A child
+//    still waiting on the ship (`josh ship:wait`) takes the stop itself, and nothing is relaunched.
 //
 // 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.
@@ -39,8 +44,27 @@ 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' | 'parked' | 'redispatch'
+// The wait for a broker on older code to be replaced: its refusal makes its supervisor reload onto the
+// current code at its next pass boundary (`run-wake-code.ts`, joshuafolkken/kit#4714), which a pass reaches
+// after a driver window and the pause between passes; a minute more covers the takeover and the
+// successor's first lane scan. A driver that reruns a busy merge holds the pass longer still, and a ship
+// past the wait is re-dispatched with the version mismatch named.
+const RELOAD_POLLS =
+	(run_wake_driver.WINDOW_MS + backlog_budget.OFFER_INTERVAL_MS) / SERVING_POLL_MS + SERVING_POLLS
+const VERSION_MISMATCH_NOTE =
+	'the lane broker runs older code than this ship (a version mismatch), and no broker on the current code read the request within the wait'
+
+type ReturnOutcome = 'relaunched' | 'returned' | 'recorded' | 'parked' | 'redispatch'
+
+// `unreadable`: the broker's code predates the request's shape, so it refused the request unread and
+// started nothing.
+type BrokerReply = 'started' | 'unreadable' | 'failed'
+
+// The broker's reply and, where it started nothing, the reason it gave.
+interface BrokerResult {
+	reply: BrokerReply
+	reason: string
+}
 
 // The failed stage's output, and its standard output alone where the stage kept it apart.
 type StageOutput = Pick<ShipSection, 'body' | 'out'>
@@ -68,14 +92,25 @@ function note(text: string): void {
 	process.stderr.write(`${text}\n`)
 }
 
-function relaunched(lane: LaneInfo, stop: ShipStop): ReturnOutcome {
+// **A relaunch that started nothing is recorded where `run:merge` reads it** (joshuafolkken/kit#4765): the
+// transcript's mtime cannot tell it from an answered stop, since the dispatch log's header is written
+// before the spawn. The reason is kept for the park a re-dispatch cap may end in.
+async function record_failed_relaunch(issue: string, reason: string): Promise<void> {
+	note(`the lane child could not be relaunched: ${reason}`)
+	await run_event_stream_emit.emit(
+		run_event_stream.EVENT_KIND.RELAUNCH_FAILED,
+		`${issue_cite.plain(issue)} could not be relaunched: ${reason}`,
+	)
+}
+
+async function relaunched(lane: LaneInfo, stop: ShipStop): Promise<ReturnOutcome> {
 	const invocation = lane_child_invocation.ship_stop_invocation(lane.issue, stop)
 	const phase = agent_role_profile.IMPLEMENTATION_PHASE
 	const result = lane_relaunch.relaunch(lane, invocation, phase, note)
 
 	if (result.kind === 'launched') return 'relaunched'
 
-	note(`the lane child could not be relaunched: ${result.note}`)
+	await record_failed_relaunch(lane.issue, result.note)
 
 	return 'recorded'
 }
@@ -83,21 +118,29 @@ 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 ask_broker(lane: LaneInfo, stop: ShipStop): Promise<boolean> {
+async function ask_broker(lane: LaneInfo, stop: ShipStop): Promise<BrokerResult> {
 	const answer = await lane_session_broker.request(lane.directory, lane.issue, {
 		kind: 'relaunch',
 		stop,
 	})
 
-	if (!answer.is_success) note(`the lane broker did not start the lane child — ${answer.reason}`)
+	if (answer.is_success) return { reply: 'started', reason: '' }
+
+	note(`the lane broker did not start the lane child — ${answer.reason}`)
 
-	return answer.is_success
+	const reply = lane_session_broker.is_unreadable(answer) ? 'unreadable' : 'failed'
+
+	return { reply, reason: answer.reason }
 }
 
-// The session of a broker serving the lane within the wait, other than `previous` — one that stopped
+// The session of a broker serving the lane within `polls` seconds, 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) {
+async function await_server(
+	lane: LaneInfo,
+	previous?: string,
+	polls = SERVING_POLLS,
+): Promise<string | undefined> {
+	for (let polled = 0; polled < polls; polled += 1) {
 		const session = lane_session_broker.serving_session(lane.directory, lane.issue)
 		if (session !== undefined && session !== previous) return session
 
@@ -108,28 +151,62 @@ async function await_server(lane: LaneInfo, previous?: string): Promise<string |
 	return undefined
 }
 
+function polls_after(reply: BrokerReply): number {
+	return reply === 'unreadable' ? RELOAD_POLLS : SERVING_POLLS
+}
+
+function redispatch_reason(last: BrokerResult): string {
+	const cause = last.reply === 'unreadable' ? `${VERSION_MISMATCH_NOTE}: ` : ''
+
+	return `${cause}the driver re-dispatches the issue — ${last.reason}`
+}
+
 // **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`).
+// issue (`run-merge-ship.ts`). A broker that could not read the request runs older code than this ship
+// (joshuafolkken/kit#4733): its successor on the current code is waited for over a whole supervisor pass, and a
+// re-dispatch past that wait names the version mismatch.
 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)
+	const first = await ask_broker(lane, stop)
+	if (first.reply === 'started') return 'relaunched'
 
-	if (next !== undefined && (await ask_broker(lane, stop))) return 'relaunched'
+	const next = await await_server(lane, server, polls_after(first.reply))
+	// The reply the issue is handed to the driver on: the new broker's where one served the lane.
+	const last = next === undefined ? first : await ask_broker(lane, stop)
+	if (last.reply === 'started') return 'relaunched'
 
-	note('the lane child could not be relaunched: the driver re-dispatches the issue')
+	await record_failed_relaunch(lane.issue, redispatch_reason(last))
 
 	return 'redispatch'
 }
 
+// **The session that launched the ship takes the stop where it still waits on it** (`run-ship-waiter.ts`),
+// so no fresh session re-reads the run; one that ended is relaunched as below (joshuafolkken/kit#4711).
+async function is_returned(issue: string, stop: ShipStop): Promise<boolean> {
+	const repository = await run_ship_probe.repository_directory()
+	if (repository === undefined) return false
+
+	const stop_note = lane_child_invocation.ship_stop_note(issue, stop)
+
+	return await run_ship_waiter.offer(repository, issue, stop_note)
+}
+
+async function relaunched_or_brokered(lane: LaneInfo, stop: ShipStop): Promise<ReturnOutcome> {
+	// 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, stop.stage)
+	// **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 ? await relaunched(lane, stop) : await brokered(lane, stop, server)
+}
+
 // 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)
-
+async function parked(issue: string, reason: string): Promise<ReturnOutcome> {
 	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')
@@ -154,18 +231,15 @@ async function stopped(
 
 	if (lane === undefined) return 'recorded'
 
-	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 reason = run_ship_stage.stop_reason(stage, resume.conflicts)
 
-	const context = await run_ship_stop_context.build(issue, output.body)
+	if (await run_ship_relaunch_cap.is_over(issue, reason)) return await parked(issue, reason)
+
+	const findings = run_ship_stop_cause.details_of(stage, { ...resume, ...output })
+	const context = await run_ship_stop_context.build(issue, output.body, findings)
 	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)
+	return (await is_returned(issue, stop)) ? 'returned' : await relaunched_or_brokered(lane, stop)
 }
 
 async function return_control(

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

@@ -0,0 +1,24 @@
+import { review_round_reuse, type ReuseAnswer } from '#scripts/review/review-round-reuse'
+
+// Why the ship's review stage ran or was skipped, written on its event line so `josh lane:breakdown`
+// shows it beside the stage's minutes (joshuafolkken/kit#5296). The stage runs only under `--review`;
+// within it, a recorded round 1 attested on this branch whose tree held, or moved only where round 2
+// reads, is reused (`review-round-reuse.ts`) — anything else is reviewed again, for the cause the reuse
+// answer names.
+
+const HELD_REASON = 'reused: round 1 attested on this branch, its tree held'
+const DELTA_REASON = "reused: round 1 attested on this branch, what moved since is round 2's delta"
+const RAN_PREFIX = 'ran: --review with no reusable round 1 — '
+const UNNAMED_CAUSE = 'the recorded round does not cover this tree'
+
+function reused(answer: ReuseAnswer): string {
+	return answer.reuse === review_round_reuse.REUSE.HELD ? HELD_REASON : DELTA_REASON
+}
+
+function ran(answer: ReuseAnswer): string {
+	return `${RAN_PREFIX}${answer.cause ?? UNNAMED_CAUSE}`
+}
+
+const run_ship_review_reason = { ran, reused }
+
+export { run_ship_review_reason }