@joshuafolkken/kit 1.1387.0 → 1.1453.0

package/scripts/run/event/run-event-checks.ts

@@ -0,0 +1,54 @@
+import { issue_cite } from '#scripts/issue/issue-cite'
+
+// The words of a `pr-checks` event (joshuafolkken/kit#3770): `josh followup` writes them and `run:board`
+// reads them back, so the one spelling lives here. A line reads
+// `#3754 PR 3765 pass 6 pending 2 fail 0 coderabbit running` — the issue first, as every event names
+// it, so the stream's readers key it to the child as they key any other.
+
+const CODERABBIT_STATES = ['running', 'done', 'rate-limited', 'failed', 'none'] as const
+
+type CodeRabbitState = (typeof CODERABBIT_STATES)[number]
+
+interface PrChecks {
+	pr: number
+	pass: number
+	pending: number
+	fail: number
+	coderabbit: CodeRabbitState
+}
+
+const CHECKS_PATTERN =
+	/^#\d+ PR (?<pr>\d+) pass (?<pass>\d+) pending (?<pending>\d+) fail (?<fail>\d+) coderabbit (?<coderabbit>\S+)$/u
+
+function text_of(issue: string, checks: PrChecks): string {
+	const { pr, pass, pending, fail, coderabbit } = checks
+
+	return `${issue_cite.plain(issue)} PR ${String(pr)} pass ${String(pass)} pending ${String(pending)} fail ${String(fail)} coderabbit ${coderabbit}`
+}
+
+const STATE_NAMES: ReadonlySet<string> = new Set(CODERABBIT_STATES)
+
+function is_coderabbit_state(value = ''): value is CodeRabbitState {
+	return STATE_NAMES.has(value)
+}
+
+// The checks a line carries, `undefined` for a line written in some other shape.
+function checks_of(text: string): PrChecks | undefined {
+	const groups = CHECKS_PATTERN.exec(text)?.groups
+	const coderabbit = groups?.['coderabbit']
+
+	if (groups === undefined || !is_coderabbit_state(coderabbit)) return undefined
+
+	return {
+		pr: Number(groups['pr']),
+		pass: Number(groups['pass']),
+		pending: Number(groups['pending']),
+		fail: Number(groups['fail']),
+		coderabbit,
+	}
+}
+
+const run_event_checks = { checks_of, text_of }
+
+export { run_event_checks }
+export type { CodeRabbitState, PrChecks }

package/scripts/run/event/run-event-render.ts

@@ -28,6 +28,7 @@ const KIND_LABELS: Readonly<Record<EventKind, KindLabel>> = {
 	outage: { ja: '障害', en: 'outage' },
 	cut: { ja: 'セッション交代', en: 'session cut' },
 	resume: { ja: '実装を再開', en: 'implementation resumed' },
+	restart: { ja: '止めて出し直し', en: 'restarted' },
 	drain: { ja: 'バックログが空', en: 'backlog drained' },
 	stop: { ja: '停止', en: 'stopped' },
 	'pr-opened': { ja: 'PR 作成', en: 'PR opened' },
@@ -45,6 +46,7 @@ const KIND_LABELS: Readonly<Record<EventKind, KindLabel>> = {
 	add: { ja: '割り込み', en: 'added' },
 	'lane-limit': { ja: 'レーン上限', en: 'lane limit' },
 	setup: { ja: '準備', en: 'setup' },
+	'pr-checks': { ja: 'PR のチェック', en: 'PR checks' },
 }
 
 const LABELS_BY_KIND: ReadonlyMap<string, KindLabel> = new Map(Object.entries(KIND_LABELS))

package/scripts/run/event/run-event-scope.ts

@@ -93,6 +93,7 @@ const KIND = run_event_stream.EVENT_KIND
 // so a lane child never reads one as its own.
 const BATCH_RECORD_KINDS: ReadonlySet<string> = new Set([
 	KIND.CHILD_LAUNCH,
+	KIND.RESTART,
 	KIND.PARK,
 	KIND.SPLIT,
 	KIND.RETROSPECTIVE,

package/scripts/run/event/run-event-setup.ts

@@ -3,10 +3,12 @@ import { error_text } from '#scripts/lib/error-message'
 import { run_event_stream } from './run-event-stream'
 import { run_event_stream_emit } from './run-event-stream-emit'
 
-// The stages a run passes between `josh backlogrun` and its first child, each written to the stream as
-// one `setup` event by the step that enters it. **The text is the stage's own words**: `run:board` draws
-// it as written, so the message a person reads and the `💓` beside it come from one event and cannot
-// disagree. Only a lane opening names an issue, which is how a reader tells it from the stages before it.
+// The stages a run passes between `josh backlogrun` and its first child, and those of a later hand-back
+// to a session, each written to the stream as one `setup` event by the step that enters it. **The text
+// is the stage's own words**: `run:board` draws it as written, so the message a person reads and the
+// `💓` beside it come from one event and cannot disagree. Only the stages of a lane's launch — opening
+// it, installing into it, dispatching its child — name an issue, which is how a reader tells them from
+// the stages before them.
 
 const STAGE = {
 	// `josh backlogrun` started the parent session, which is reading its procedure.
@@ -15,33 +17,75 @@ const STAGE = {
 	PLANNING: 'planning',
 	// The supervisor took the run over from the parent and is asking for the first offer.
 	HANDING_OFF: 'handing off',
+	// The driver answered something only a session can act on — an untriaged child, an epic left to a
+	// person — and the supervisor is waking one. The next hand-off replaces it.
+	JUDGING: 'waiting on judgment',
+	// The supervisor started that session, which is now acting on the driver's answer. It is detached, so
+	// its end is the supervisor's next hand-off, which replaces this.
+	SESSION: 'judgment session running',
+	// The driver's launch of a lane returned without a child: no lane was free to open, or a step after
+	// the open failed. It names no issue, so the lane's own stage ends here whatever the driver does next.
+	NO_CHILD: 'no child launched',
 } as const
 
 const OPENING = 'opening lane'
+const INSTALLING = 'installing dependencies'
+const DISPATCHING = 'dispatching'
+// The stages of one lane's launch, in the order a lane passes them.
+const LANE_STAGE = { OPENING, INSTALLING, DISPATCHING } as const
 
 // The driver is about to open a lane for `issue` — for every child, not only the first.
 function opening_lane(issue: string): string {
 	return `${OPENING} ${issue_cite.plain(issue)}`
 }
 
+// The lane's work tree exists and its dependencies are about to be installed into it.
+function installing(issue: string): string {
+	return `${INSTALLING} ${issue_cite.plain(issue)}`
+}
+
+// The lane is ready and its child is about to be dispatched; the child's own `child-launch` follows.
+function dispatching(issue: string): string {
+	return `${DISPATCHING} ${issue_cite.plain(issue)}`
+}
+
 // Best-effort, as every append to this stream is: a stage that could not be written is a board that
 // says less, never a run that failed.
 async function emit(text: string): Promise<void> {
 	await run_event_stream_emit.emit(run_event_stream.EVENT_KIND.SETUP, text)
 }
 
-// The same append for a caller that already holds the repository's common git directory and the moment
-// it wants the stage dated — the launcher, whose record and first stage carry one time.
-function emit_in(repository: string, text: string, at: Date): void {
+// The same append to a stream the caller resolves, dated the moment it hands over.
+function append_stage(resolve_target: () => string, text: string, at: Date): void {
 	try {
-		const target = run_event_stream.target_of(repository)
+		const { SETUP } = run_event_stream.EVENT_KIND
 
-		run_event_stream.append(target, run_event_stream.EVENT_KIND.SETUP, text, at.toISOString())
+		run_event_stream.append(resolve_target(), SETUP, text, at.toISOString())
 	} catch (error) {
-		error_text.trace_swallowed('run_event_setup.emit_in', error)
+		error_text.trace_swallowed('run_event_setup.append_stage', error)
 	}
 }
 
-const run_event_setup = { STAGE, emit, emit_in, opening_lane }
+// For a caller that already holds the repository's common git directory and the moment it wants the
+// stage dated — the launcher, whose record and first stage carry one time.
+function emit_in(repository: string, text: string, at: Date): void {
+	append_stage(() => run_event_stream.target_of(repository), text, at)
+}
+
+// For a caller that already holds the stream's own path — the supervisor, which resolved it once.
+function emit_to(target: string, text: string, at: Date): void {
+	append_stage(() => target, text, at)
+}
+
+const run_event_setup = {
+	LANE_STAGE,
+	STAGE,
+	dispatching,
+	emit,
+	emit_in,
+	emit_to,
+	installing,
+	opening_lane,
+}
 
 export { run_event_setup }

package/scripts/run/event/run-event-stream.ts

@@ -60,6 +60,10 @@ const EVENT_KIND = {
 	// resume clears the cut record, so without this the `cut` would stay the newest position and
 	// `run:step` would keep answering the resume command it had just run.
 	RESUME: 'resume',
+	// A person stopped a running lane child and re-dispatched its issue in a fresh session
+	// (`lane:restart`). It follows the fresh dispatch's `CHILD_LAUNCH`, so it is a launch to the parent and
+	// the board, and — like that launch — a batch record a lane child never reads as its own position.
+	RESTART: 'restart',
 	// The backlog emptied while nothing of the run's own was in flight — the drain. It marks the position
 	// at which the end-of-run retrospective is owed, *before* the idle watch opens, so `run:step` fires
 	// the retrospective at the drain rather than after the watch runs its course. It is not itself a
@@ -126,10 +130,15 @@ const EVENT_KIND = {
 	// already holds. A trace: it says the run gained room, not where the run is.
 	LANE_LIMIT: 'lane-limit',
 	// One stage of the run's start — the session starting, the plan, the hand-off to the supervisor, a
-	// lane opening (`run-event-setup.ts`). `run:board` draws it until the first child launches, so the
+	// lane opening (`run-event-setup.ts`). `run:board` draws it while the run stands at it, so the
 	// minutes before one read as work rather than as a run that has stopped. A trace: it says the run is
 	// getting ready, not where the run is.
 	SETUP: 'setup',
+	// A child's pull request checks as `josh followup` last polled them — the CI counts and CodeRabbit's
+	// state (`run-event-checks.ts`), written only when they change, so `run:board` draws a child waiting
+	// in followup without asking GitHub (joshuafolkken/kit#3770). A trace: it says how the checks stand,
+	// not where the run is.
+	PR_CHECKS: 'pr-checks',
 } as const
 
 type EventKind = (typeof EVENT_KIND)[keyof typeof EVENT_KIND]
@@ -148,17 +157,19 @@ const TRACE_KINDS: ReadonlySet<string> = new Set([
 	EVENT_KIND.ADD,
 	EVENT_KIND.LANE_LIMIT,
 	EVENT_KIND.SETUP,
+	EVENT_KIND.PR_CHECKS,
 ])
 
 // The trace kinds that say only that the run was alive, so the bound rolls them off first. A `filed` or
 // `note` line is a trace to the position readers but is the board's record of what the run found, so
 // it rolls off only with the positions. A ship-stage `start` is disposable but goes last of them:
-// `run:board` draws from that line. A `setup` line is read only until the child it prepares launches,
-// so every one but the newest goes.
+// `run:board` draws from that line. Only the newest `setup` line is the stage the run stands at,
+// so every one but the newest goes; likewise only each child's newest `pr-checks` is drawn.
 const DISPOSABLE_KINDS: ReadonlySet<string> = new Set([
 	EVENT_KIND.SHIP_STAGE,
 	EVENT_KIND.HEARTBEAT,
 	EVENT_KIND.SETUP,
+	EVENT_KIND.PR_CHECKS,
 ])
 
 const event_schema = z.object({
@@ -229,17 +240,18 @@ function last_position(events: ReadonlyArray<RunEvent>): number {
 	return events[events.length - POSITION_INCREMENT]?.pos ?? FIRST_POSITION
 }
 
-// The issue a ship-stage names — `#<N> <stage> <phase>` carries it first.
+// The issue a ship-stage or a `pr-checks` line names — `#<N> …` carries it first.
 function issue_of(event: RunEvent): string {
 	return event.text.split(WORD_SEPARATOR)[FIRST_POSITION] ?? ''
 }
 
-// Each issue's newest ship-stage, the one the board reads its furthest phase from.
-function newest_stages(events: ReadonlyArray<RunEvent>): ReadonlySet<RunEvent> {
+// Each issue's newest line of one kind: the ship-stage the board reads its furthest phase from, and the
+// `pr-checks` it draws a followup row's end from.
+function newest_by_issue(events: ReadonlyArray<RunEvent>, kind: string): ReadonlySet<RunEvent> {
 	const newest = new Map<string, RunEvent>()
 
 	for (const event of events) {
-		if (event.kind === EVENT_KIND.SHIP_STAGE) newest.set(issue_of(event), event)
+		if (event.kind === kind) newest.set(issue_of(event), event)
 	}
 
 	return new Set(newest.values())
@@ -253,12 +265,16 @@ function is_stage_start(event: RunEvent): boolean {
 	return event.text.split(WORD_SEPARATOR)[STAGE_PHASE_INDEX] === run_ship_stage.PHASE.START
 }
 
-// The disposable lines the bound never drops: each issue's newest ship-stage and the run's newest
-// `setup` stage, the ones `run:board` draws from now.
+// The disposable lines the bound never drops: each issue's newest ship-stage and `pr-checks` and the
+// run's newest `setup` stage, the ones `run:board` draws from now.
 function drawn_lines(events: ReadonlyArray<RunEvent>): ReadonlySet<RunEvent> {
 	const setup = events.findLast((event) => event.kind === EVENT_KIND.SETUP)
 
-	return new Set([...newest_stages(events), ...(setup === undefined ? [] : [setup])])
+	return new Set([
+		...newest_by_issue(events, EVENT_KIND.SHIP_STAGE),
+		...newest_by_issue(events, EVENT_KIND.PR_CHECKS),
+		...(setup === undefined ? [] : [setup]),
+	])
 }
 
 // The lines the bound may drop, in the order it drops them: the ones that draw nothing first, then the
@@ -282,7 +298,7 @@ function droppable(events: ReadonlyArray<RunEvent>): ReadonlyArray<RunEvent> {
 // **Each issue's newest ship-stage is not disposable**: it is the only record `run:board` draws a lane's
 // review-and-later phase from, and on a stream full of positions it would otherwise roll off in its own
 // append. **The newest `setup` stage is kept for the same reason**: it is the stage `run:board` draws
-// until the first child launches, and a run that starts on a full stream would otherwise show none.
+// while the run stands at it, and a run that starts on a full stream would otherwise show none.
 //
 // **A ship-stage `start` outlasts the other disposable lines**: each one is a phase on the lane's track,
 // so it is kept past the `done` lines and the heartbeats.

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

@@ -25,7 +25,7 @@ import { run_merge_token, type MergeToken } from './run-merge-token'
 // The contract is `run:carry`'s: **standard output carries one token** (or the newline-separated
 // offer `epic:next --lanes` prints), and everything else is a captured subprocess or a quiet
 // in-process call. The verdicts this command adds to the offer are `over` (hand off), `human-review`
-// (stop — the child's own ending), `stop` (the consecutive-failure guard tripped) and `retry` (the
+// (stop — the child's own ending), `stop` (the consecutive-failure guard tripped, or a failed child could not be parked) and `retry` (the
 // child's state could not be read; re-read before deciding).
 
 const ARGV_OFFSET = 2
@@ -163,13 +163,16 @@ function parse(argv: ReadonlyArray<string>): MergeContext | undefined {
 interface ControlVerdict {
 	token: MergeToken
 	code: number
+	is_offer: false
 }
 
 // The next child offered in the collected one's place: the text `backlog:next` or `epic:next --lanes`
-// printed, passed through as it was read, so no narrower type holds it.
+// printed, passed through as it was read, so no narrower type holds it. `is_offer` keeps its `stop`
+// apart from the control one (`run_merge_token.is_control_stop`).
 interface OfferVerdict {
 	token: string
 	code: number
+	is_offer: true
 }
 
 type MergeVerdict = ControlVerdict | OfferVerdict
@@ -179,11 +182,11 @@ type MergeVerdict = ControlVerdict | OfferVerdict
 type MergeResult = MergeVerdict & { outcome: ChildOutcome }
 
 function emit(token: MergeToken, code: number): ControlVerdict {
-	return { token, code }
+	return { token, code, is_offer: false }
 }
 
 async function offered(ctx: MergeContext): Promise<OfferVerdict> {
-	return { token: await run_merge_steps.ask_next(ctx), code: SUCCESS_EXIT_CODE }
+	return { token: await run_merge_steps.ask_next(ctx), code: SUCCESS_EXIT_CODE, is_offer: true }
 }
 
 // Whether the child's exit record shows it could not reach the API — read only when `--output` named

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

@@ -0,0 +1,61 @@
+import { git_common_directory } from '#scripts/git/git-common-directory'
+import { run_event_scope } from '#scripts/run/event/run-event-scope'
+import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-stream'
+import { run_ship_detach } from '#scripts/run/ship/run-ship-detach'
+
+// Why `run:merge` parks a child whose detached ship has already ended (joshuafolkken/kit#3808).
+//
+// **A child that handed its region to `josh ship --detach` is parked for what its ship did.** A running
+// ship is never parked (`merge_child` answers `shipping` first), so a park after a hand-off means the
+// ship ended unmerged — and the session the ship relaunched to fix it ended too. The generic "session
+// ended with its issue open" then hides the one fact a person needs: the stage the ship stopped at. The
+// cause is that stage's `ship-stop` line, written by the supervisor since its own launch; a ship that
+// ended without one (killed, or failed before any stage) is named by its result and its log instead.
+
+type ShipEnding = ReturnType<typeof run_ship_detach.read_result>
+
+const ENDED_RESULTS: ReadonlySet<string> = new Set(['failed', 'abnormal'])
+
+type Events = ReadonlyArray<RunEvent>
+
+// `child`'s events after its newest `ship-launch`, so an earlier launch's stop the relaunched session
+// already fixed is never blamed for this ending. The record and the stream outlive a dispatch, so only a
+// ship launched since the child's own newest dispatch is this attempt's: an earlier attempt's ended ship
+// answers `undefined`, never this park.
+function since_ship_launch(events: Events, child: string): Events | undefined {
+	const attempt = run_event_scope.since_own_launch(events, child)
+	const own = attempt.filter((event) => run_event_scope.issue_named(event) === child)
+	const launched_at = own.findLastIndex(
+		(event) => event.kind === run_event_stream.EVENT_KIND.SHIP_LAUNCH,
+	)
+
+	return launched_at === -1 ? undefined : own.slice(launched_at + 1)
+}
+
+function cause_of(ending: ShipEnding, events: Events, child: string): string | undefined {
+	if (ending === undefined || !ENDED_RESULTS.has(ending.result)) return undefined
+
+	const attempt = since_ship_launch(events, child)
+	if (attempt === undefined) return undefined
+
+	const stop = attempt.findLast((event) => event.kind === run_event_stream.EVENT_KIND.SHIP_STOP)
+
+	if (stop !== undefined) return `its detached ship stopped and was not fixed: ${stop.text}.`
+
+	return `its detached ship ended ${ending.result} before recording a stopped stage — pnpm josh ship --log ${child}.`
+}
+
+// The ship's cause for `child`'s park, read from the record and the stream this checkout's repository
+// keys on, or `undefined` when the child handed nothing to a ship or its ship succeeded.
+function cause(child: string, directory: string = process.cwd()): string | undefined {
+	const repository = git_common_directory.repository(directory)
+	if (repository === undefined) return undefined
+
+	const events = run_event_stream.read_events(run_event_stream.target_of(repository))
+
+	return cause_of(run_ship_detach.read_result(repository, child), events, child)
+}
+
+const run_merge_ship = { cause, cause_of }
+
+export { run_merge_ship }

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

@@ -9,6 +9,7 @@ import { NEEDS_DECISION_LABEL } from '#scripts/issue/issue-labels'
 import { session_cite } from '#scripts/issue/session-cite'
 import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
 import { lane_close } from '#scripts/lane/lane-close'
+import { lane_preserve } from '#scripts/lane/lane-preserve'
 import { lane_reap } from '#scripts/lane/lane-reap'
 import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
 import { lane_relaunch } from '#scripts/lane/lane-relaunch'
@@ -24,6 +25,7 @@ import { run_carry_conversation } from '#scripts/run/carry/run-carry-conversatio
 import { run_cut, type RunCut } from '#scripts/run/cut/run-cut'
 import { run_label } from '#scripts/run/run-label'
 import { run_merge } from './run-merge'
+import { run_merge_ship } from './run-merge-ship'
 
 // The result of attempting to apply a carry change. Distinguishing `refused` from `applied` lets
 // callers surface the refusal as a hard failure rather than silently continuing on a carry that was
@@ -167,18 +169,8 @@ async function close_lane(child: string): Promise<void> {
 	await josh(['lane:close', child])
 }
 
-function preserved_comment(message: string): string {
-	return [
-		'The lane held uncommitted work when `run:merge` closed it, so it was stashed before the close:',
-		`- recover with \`pnpm josh stash:pop "${message}"\``,
-	].join('\n')
-}
-
 async function stash_work(child: string, directory: string): Promise<void> {
-	const message = git_stash.work_message(child, LANE_CLOSE_OCCASION)
-
-	await git_stash.push(message, directory)
-	await git_gh_issue_write.issue_try_comment(child, preserved_comment(message))
+	await lane_preserve.stash_work(child, directory, LANE_CLOSE_OCCASION, '`run:merge` closed it')
 }
 
 // Stash whatever the lane still holds uncommitted before its tree is removed: `lane:close` deletes by
@@ -344,13 +336,14 @@ async function park_failed(ctx: MergeContext, cause: string): Promise<FailedResu
 }
 
 // A child that ended unfinished: waiting when it records an open blocker (`do_waiting`), parked
-// otherwise (`park_failed`) — an order already recorded is never a decision for a person.
-async function do_failed(ctx: MergeContext, cause: string = FAILED_CAUSE): Promise<FailedResult> {
+// otherwise (`park_failed`) — an order already recorded is never a decision for a person. Without a
+// cause of the caller's, a child whose detached ship ended is parked for the ship's stop.
+async function do_failed(ctx: MergeContext, cause?: string): Promise<FailedResult> {
 	const blockers = await open_blockers(ctx.child)
 
 	if (blockers.length > 0) return await do_waiting(ctx, blockers)
 
-	return await park_failed(ctx, cause)
+	return await park_failed(ctx, cause ?? run_merge_ship.cause(ctx.child) ?? FAILED_CAUSE)
 }
 
 // The outcome of counting an outage: the record to read the streak against, and whether the count was

package/scripts/run/merge/run-merge-token.ts

@@ -24,7 +24,21 @@ const MERGE_TOKEN = {
 
 type MergeToken = (typeof MERGE_TOKEN)[keyof typeof MERGE_TOKEN]
 
-const run_merge_token = { MERGE_TOKEN }
+// Where the token came from: `run:merge`'s own control verdict, or the next offer (`backlog:next` /
+// `epic:next`) passed through as it was read. The offer has a `stop` of its own — nothing ready to start
+// is left — spelled like the control `stop`, so the source travels beside the token.
+interface MergeTokenRead {
+	token: string
+	is_offer: boolean
+}
 
-export type { MergeToken }
+// The single reading of "this merge stopped the run": the control `stop` alone. An offer's `stop` is a
+// parked backlog, which `backlog:budget` decides — a watch while the idle budget lasts — never the merge.
+function is_control_stop(read: MergeTokenRead): boolean {
+	return !read.is_offer && read.token === MERGE_TOKEN.STOP
+}
+
+const run_merge_token = { MERGE_TOKEN, is_control_stop }
+
+export type { MergeToken, MergeTokenRead }
 export { run_merge_token }

package/scripts/run/run-headless.ts

@@ -129,6 +129,7 @@ const run_headless = {
 	is_backlog_parent,
 	is_cut_capped,
 	is_headless,
+	is_headless_parent,
 	is_owned_here,
 	must_keep_waiting,
 }

package/scripts/run/run-step.ts

@@ -222,6 +222,8 @@ const FULL_INPUT_ACTIONS: Record<string, (input: StepInput) => StepAction> = {
 	[KIND.STOP]: stop_action,
 	[KIND.DRAIN]: drain_action,
 	[KIND.CHILD_LAUNCH]: child_launch_action,
+	// A person's restart re-dispatched the child, so the parent's position is a launch's.
+	[KIND.RESTART]: child_launch_action,
 }
 
 // An event the table does not name leaves the position unknown rather than guessing a next step. A

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

@@ -274,6 +274,18 @@ async function open_context(args: ShipArguments): Promise<ShipContext> {
 	return { target, done, state, started }
 }
 
+// Every stop goes to the lane ledger — supervised, in an agent's own turn, or a lane child's preflight
+// before the hand-off — so `lane:stats` can say how long a ship stayed stopped for each reason.
+async function record_stop(
+	args: ShipArguments,
+	stage: Stage,
+	conflicts?: ReadonlyArray<string>,
+): Promise<void> {
+	const reason = run_ship_stage.stop_reason(stage, conflicts)
+
+	await lane_ledger.record_stop({ issue: Number(args.number), reason })
+}
+
 // A detached supervisor hands the stopped stage back (`run-ship-return.ts`); a
 // ship in an agent's own turn has its report in front of that agent already. The `ship-stop` ends the
 // attempt, so the record's started stages go with it.
@@ -283,8 +295,11 @@ async function stopped(
 	step: Step,
 	context: ShipContext,
 ): Promise<ReadonlyArray<ShipSection>> {
+	const conflicts = sections.at(-1)?.conflicts
+
+	await record_stop(args, step.stage, conflicts)
+
 	if (run_ship_detach.is_supervised()) {
-		const conflicts = sections.at(-1)?.conflicts
 		const resume = run_ship_next.resume_of(args)
 
 		record(context.target, run_ship_stage.end_attempt)
@@ -371,7 +386,12 @@ function should_detach(args: ShipArguments): boolean {
 // 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))
-	if (preflight.code !== SUCCESS_EXIT_CODE) return [preflight]
+
+	if (preflight.code !== SUCCESS_EXIT_CODE) {
+		await record_stop(args, run_ship_steps.PREFLIGHT_STEP.stage)
+
+		return [preflight]
+	}
 
 	const result = await run_ship_pre_detach.checks()
 

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

@@ -1,8 +1,9 @@
 import { agent_role_profile } from '#scripts/agent/agent-role-profile'
-import { lane_child_invocation } from '#scripts/lane/lane-child-invocation'
+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'
 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'
@@ -49,6 +50,31 @@ function note(text: string): void {
 	process.stderr.write(`${text}\n`)
 }
 
+function relaunched(lane: LaneInfo, stop: ShipStop): 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}`)
+
+	return 'recorded'
+}
+
+// **A served lane's child is relaunched by its broker, not from here**: this supervisor descends from the
+// child's Bash tool, which Claude Code starts without the token, so a child started here could not sign
+// in where the token is the only credential (joshuafolkken/kit#3817).
+async function brokered(lane: LaneInfo, stop: ShipStop): Promise<ReturnOutcome> {
+	if (await lane_session_broker.request(lane.directory, lane.issue, { kind: 'relaunch', stop })) {
+		return 'relaunched'
+	}
+
+	note('the lane child could not be relaunched: the lane broker did not start it')
+
+	return 'recorded'
+}
+
 async function return_control(
 	issue: string,
 	stage: Stage,
@@ -63,19 +89,11 @@ async function return_control(
 
 	if (lane === undefined) return 'recorded'
 
-	const invocation = lane_child_invocation.ship_stop_invocation(issue, { stage, ...resume })
-	const result = lane_relaunch.relaunch(
-		lane,
-		invocation,
-		agent_role_profile.IMPLEMENTATION_PHASE,
-		note,
-	)
+	const stop = { stage, ...resume }
 
-	if (result.kind === 'launched') return 'relaunched'
-
-	note(`the lane child could not be relaunched: ${result.note}`)
-
-	return 'recorded'
+	return lane_session_broker.is_serving(lane.directory, issue)
+		? await brokered(lane, stop)
+		: relaunched(lane, stop)
 }
 
 const run_ship_return = { return_control }

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

@@ -4,7 +4,7 @@ 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 { openai_review_broker } from '#scripts/lane/openai-review-broker'
+import { lane_session_broker } from '#scripts/lane/lane-session-broker'
 import { review_record } from '#scripts/review/review-record'
 import { detached_launch } from '#scripts/run/detached-launch'
 import { run_ship_review, type RoundOutcome, type ScoredVerdict } from './run-ship-review'
@@ -66,7 +66,7 @@ function failure(out: string): JoshResult {
 }
 
 function paths(): { brief: string; findings: string; log: string } {
-	return openai_review_broker.review_paths(PROJECT_ROOT)
+	return lane_session_broker.review_paths(PROJECT_ROOT)
 }
 
 async function josh(argv: ReadonlyArray<string>): Promise<JoshResult> {
@@ -94,6 +94,16 @@ async function run_direct_session(
 	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,
@@ -103,11 +113,14 @@ async function run_session(
 	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 (built.profile.provider !== 'openai' || !lane_child_marker.is_child_of(PROJECT_ROOT)) {
+	if (!is_brokered(built.profile, issue)) {
 		return await run_direct_session(built.argv, built.profile, log_path)
 	}
 
-	const is_success = await openai_review_broker.request(PROJECT_ROOT, issue, round)
+	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')
 }