@joshuafolkken/kit 1.1471.0 → 1.1784.0

package/scripts/lane/lane-close.ts

@@ -4,8 +4,11 @@ import { git_worktree } from '#scripts/git/git-worktree'
 import { error_text } from '#scripts/lib/error-message'
 import { lane_paths } from './lane-paths'
 import { lane_reap } from './lane-reap'
+import { lane_reap_settle } from './lane-reap-settle'
 import { lane_registry, type LaneInfo } from './lane-registry'
+import { lane_residents } from './lane-residents'
 import { lane_spent, type KeptLane } from './lane-spent'
+import { lane_state } from './lane-state'
 
 // Closing a lane: no work tree, no branch, no directory.
 //
@@ -13,7 +16,8 @@ import { lane_spent, type KeptLane } from './lane-spent'
 // every step here is written to run over a subject that is already gone or that still holds
 // uncommitted work. A close that refused either would leave exactly the debris it exists to remove,
 // and the next lane for that issue would then fail on a directory nobody could account for. There
-// is no ledger entry to remove: the lane's seat lived in the `.env` that goes with the work tree.
+// is no ledger entry to remove: the lane's seat lived in the `.env` that goes with the work tree. The
+// lane's state record outlives it, marked `ended`, so its last state stays readable.
 
 interface LaneTargets {
 	directory: string
@@ -36,6 +40,9 @@ interface CloseOutcome {
 	left_behind: Array<string>
 	// The lane child's processes this close terminated — empty for a child that ended by itself.
 	reaped: Array<number>
+	// What else still ran from the lane's checkout or carried its mark and this close terminated
+	// (`lane-residents.ts`); `undefined` where the processes could not be read.
+	residents: Array<number> | undefined
 }
 
 interface SweepOutcome {
@@ -112,39 +119,72 @@ function close_kind(did_exist: boolean, left_behind: ReadonlyArray<string>): Clo
 	return did_exist ? 'closed' : 'none'
 }
 
-// The main work tree's root, not this one's — the same reading `list_lanes` uses, so the fallback
-// directory an unregistered lane is closed by is the one `lane:open` would have created.
-// Derived here from the current work tree, a close run inside a lane
-// reports `none` over a directory that is still on disk.
-async function lane_root_directory(): Promise<string> {
-	return lane_paths.lane_root(await lane_registry.main_repository_root())
-}
-
+// The lane root is the main work tree's (`lane_root_directory`), so the fallback directory an
+// unregistered lane is closed by is the one `lane:open` would have created.
 /**
  * Close the lane for `issue`. `none` means there was nothing there, which is not a failure: a caller
  * cleaning up after an interruption cannot know whether the lane was ever opened. `incomplete` means
  * something survived the removal, and `left_behind` names it.
  */
 async function resolve_lane(issue: string): Promise<ResolvedLane> {
-	const root = await lane_root_directory()
+	const root = await lane_registry.lane_root_directory()
 	const existing = lane_registry.find_lane(await lane_registry.list_lanes(), issue)
 
 	return { existing, targets: lane_targets(root, issue, existing) }
 }
 
+// A lane closed before is `none` on a retry, and ends there once its record says it is not over —
+// an issue never opened is not given a record.
+async function is_ending(issue: string, kind: CloseKind): Promise<boolean> {
+	if (kind !== 'none') return kind === 'closed'
+
+	const record = await lane_state.read_state(issue)
+
+	return record !== undefined && record.state !== 'ended'
+}
+
+// The lane's processes, settled after the removal so the processes have had the work tree's deletion
+// to exit in too; what outlived the SIGKILL replaces what the lane's record noted for `run:board`.
+async function survivors_of(issue: string, directory: string): Promise<Array<string>> {
+	const survivors = await lane_reap_settle.settle({ issue, directory })
+
+	if (survivors !== undefined) await lane_state.record_stuck(issue, survivors)
+
+	return lane_reap_settle.survivor_texts(survivors)
+}
+
+// Whatever the removal left: the checkout's residue, then the processes that outlived it.
+async function left_behind_of(issue: string, targets: LaneTargets): Promise<Array<string>> {
+	const survivors = await survivors_of(issue, targets.directory)
+
+	return [...(await residue(targets)), ...survivors]
+}
+
 async function close_lane(issue: string): Promise<CloseOutcome> {
 	const { existing, targets } = await resolve_lane(issue)
 	const did_exist = existing !== undefined || existsSync(targets.directory)
 	// Before the removal, not after: a child still running in the tree would keep writing into a
 	// directory being deleted, and a process outliving its lane is a half-discarded state — the work
-	// tree gone, the child still answering `alive`.
-	const reaped = lane_reap.reap_child(issue)
+	// tree gone, the child still answering `alive`. What else still runs from the checkout goes too.
+	const reaped = lane_reap.reap_child({ issue, directory: targets.directory })
+	const residents = lane_residents.end_residents({ issue, directory: targets.directory }, reaped)
 
 	await remove_lane(targets)
 
-	const left_behind = await residue(targets)
+	const left_behind = await left_behind_of(issue, targets)
+	const kind = close_kind(did_exist, left_behind)
+
+	if (await is_ending(issue, kind)) {
+		await lane_state.record_change({ issue, state: 'ended', command: 'lane:close' })
+	}
+
+	return { issue, kind, left_behind, reaped, residents }
+}
+
+type DuePredicate = (issue: string) => Promise<boolean>
 
-	return { issue, kind: close_kind(did_exist, left_behind), left_behind, reaped }
+async function always_due(): Promise<boolean> {
+	return true
 }
 
 // A lane that could not be closed is recorded rather than thrown: a sweep has to attempt every lane,
@@ -163,14 +203,24 @@ async function try_close(issue: string): Promise<boolean> {
 
 // Sequential on purpose: two `git worktree` writes at once contend for the same registration
 // directory, and the whole point of the command is that nothing is left half-removed.
-async function close_each(issues: ReadonlyArray<string>): Promise<SweepOutcome> {
+async function close_into(sweep: SweepOutcome, issue: string, is_due: DuePredicate): Promise<void> {
+	if (!(await is_due(issue))) return
+	const bucket = (await try_close(issue)) ? sweep.closed : sweep.failed
+
+	bucket.push(issue)
+}
+
+// `is_due` is asked right before each close, not for every issue up front: a close can wait out the
+// grace window, and a lane opened again meanwhile is no longer one to close.
+async function close_each(
+	issues: ReadonlyArray<string>,
+	is_due: DuePredicate = always_due,
+): Promise<SweepOutcome> {
 	const sweep: SweepOutcome = { closed: [], failed: [] }
 
 	for (const issue of issues) {
 		// eslint-disable-next-line no-await-in-loop -- worktree writes contend for the same registration directory
-		const bucket = (await try_close(issue)) ? sweep.closed : sweep.failed
-
-		bucket.push(issue)
+		await close_into(sweep, issue, is_due)
 	}
 
 	return sweep
@@ -196,11 +246,29 @@ async function close_all_lanes(): Promise<SweepOutcome> {
 	return await close_each(lanes.map((lane) => lane.issue))
 }
 
+async function is_unfinished(issue: string): Promise<boolean> {
+	const { targets } = await resolve_lane(issue)
+
+	return !existsSync(targets.directory)
+}
+
+/**
+ * Close again every lane whose work tree is gone but whose record is not `ended` — a close a process
+ * outlived. The supervisor runs it each pass, so a lane ends once its last process does.
+ */
+async function retry_closes(): Promise<SweepOutcome> {
+	const records = await lane_state.read_records()
+	const issues = records.filter((record) => record.state !== 'ended').map(({ issue }) => issue)
+
+	return await close_each(issues, is_unfinished)
+}
+
 const lane_close = {
 	close_all_lanes,
 	close_lane,
 	prune_lanes,
 	resolve_lane,
+	retry_closes,
 }
 
 export type { CloseKind, CloseOutcome, PruneOutcome, ResolvedLane, SweepOutcome }

package/scripts/lane/lane-core-wait-stats.ts

@@ -0,0 +1,66 @@
+import { lane_ledger, type CoreWaitEntry, type LedgerEntry } from './lane-ledger'
+import { lane_stage_stats } from './lane-stage-stats'
+import { lane_stats, type StatsWindow } from './lane-stats'
+
+// How long each lane's commands waited for the core budget: the ledger's `core-wait` entries of one
+// period reduced to one row per lane, printed by `josh lane:stats` so a lane's time splits into work
+// and waiting (joshuafolkken/kit#4382). A lane is named by its issue number, a wait outside a lane — the
+// main checkout's — by its own row.
+
+const COLUMNS = ['lane', 'total (min)', 'median (min)', 'waits'] as const
+const OUTSIDE_A_LANE = 'outside a lane'
+const { NOT_MEASURED } = lane_stage_stats
+// A period with no wait: the table still prints, so a reader sees zero waits rather than no table.
+const NONE_ROW = ['none', NOT_MEASURED, NOT_MEASURED, '0']
+
+function is_core_wait(entry: LedgerEntry): entry is CoreWaitEntry {
+	return entry.kind === lane_ledger.KIND.CORE_WAIT
+}
+
+function lane_of(wait: CoreWaitEntry): string {
+	return wait.issue === undefined ? OUTSIDE_A_LANE : String(wait.issue)
+}
+
+function total(values: ReadonlyArray<number>): number {
+	return values.reduce((sum, value) => sum + value, 0)
+}
+
+function waits_of(waits: ReadonlyArray<CoreWaitEntry>, lane: string): Array<number> {
+	return waits.filter((wait) => lane_of(wait) === lane).map((wait) => wait.waited_ms)
+}
+
+function lane_row(lane: string, waits: ReadonlyArray<CoreWaitEntry>): string {
+	const waited = waits_of(waits, lane)
+
+	return lane_stats.to_row([
+		lane,
+		lane_stage_stats.cell(total(waited)),
+		lane_stage_stats.cell(lane_stats.median(waited)),
+		String(waited.length),
+	])
+}
+
+// The lanes the period saw, the longest total first, so the lane the budget held back most leads.
+function lanes_of(waits: ReadonlyArray<CoreWaitEntry>): Array<string> {
+	const lanes = [...new Set(waits.map((wait) => lane_of(wait)))]
+
+	return lanes.toSorted(
+		(left, right) => total(waits_of(waits, right)) - total(waits_of(waits, left)),
+	)
+}
+
+// The period's table: `entries` is the whole ledger, filtered here to `window`.
+function table(entries: ReadonlyArray<LedgerEntry>, window: StatsWindow): string {
+	const waits = lane_stats.in_window(entries, window).filter((entry) => is_core_wait(entry))
+	const rows = lanes_of(waits).map((lane) => lane_row(lane, waits))
+
+	return [
+		lane_stats.to_row(COLUMNS),
+		lane_stats.to_row(COLUMNS.map(() => '---')),
+		...(rows.length === 0 ? [lane_stats.to_row(NONE_ROW)] : rows),
+	].join('\n')
+}
+
+const lane_core_wait_stats = { table }
+
+export { lane_core_wait_stats }

package/scripts/lane/lane-dispatch.ts

@@ -7,9 +7,10 @@ import { IN_PROGRESS_LABEL } from '#scripts/issue/issue-labels'
 import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { session_cite } from '#scripts/issue/session-cite'
 import { telegram_notify } from '#scripts/notify/telegram-notify'
-import { detached_launch } from '#scripts/run/detached-launch'
+import { detached_launch, type LaunchArgv } from '#scripts/run/detached-launch'
 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_park } from '#scripts/run/park/run-park'
 import { run_ending } from '#scripts/run/run-ending'
 import { run_label } from '#scripts/run/run-label'
 import { lane_child_invocation } from './lane-child-invocation'
@@ -19,6 +20,7 @@ import { lane_ledger } from './lane-ledger'
 import { lane_output } from './lane-output'
 import { lane_registry, type LaneInfo } from './lane-registry'
 import { lane_resume, type ResumePlan } from './lane-resume'
+import { lane_state } from './lane-state'
 import { openai_lane_supervisor } from './openai-lane-supervisor'
 
 // `josh lane:dispatch <issue-number>` — start a lane's child as an operating-system process of its own.
@@ -197,7 +199,7 @@ function existing_dispatch(request: StartRequest): DispatchOutcome | undefined {
 	return dispatched_of(request, active.pid, [])
 }
 
-function launch_argv(request: StartRequest, nonce: string | undefined): AgentArgv {
+function launch_argv(request: StartRequest, nonce: string | undefined): LaunchArgv {
 	if (request.profile.provider !== 'openai') return request.argv
 	if (nonce === undefined) throw new Error('OpenAI supervisor nonce is missing')
 
@@ -244,10 +246,15 @@ async function dispatched_start(
 		: dispatched_of(request, pid, notes)
 }
 
+// **A dispatch takes back any park the issue's earlier child recorded**: the issue is offered
+// again only once `needs-decision` is off, so a record still on disk is one a person cleared by hand on
+// GitHub, and left in place it would silence `lane-park` on this child's own stop
+// (joshuafolkken/kit#4132).
 async function started(request: StartRequest): Promise<DispatchOutcome> {
 	const notes: Array<string> = []
 	const existing = existing_dispatch(request)
 	if (existing !== undefined) return existing
+	run_park.clear(request.lane.issue, request.lane.directory)
 	const nonce =
 		request.profile.provider === 'openai' ? openai_lane_supervisor.new_nonce() : undefined
 	const result = detached_launch.launch(
@@ -327,13 +334,27 @@ async function mark_in_progress(issue: string): Promise<LabelWrite> {
 // removal warns and never throws, so it cannot turn a launch failure into a thrown error.
 //
 // The lane ledger takes the same instant: `lane:stats` times a lane's implementation from it, and the
-// stream is capped, so a period's earlier dispatches would be gone from there.
-async function record_started(issue: string): Promise<void> {
+// stream is capped, so a period's earlier dispatches would be gone from there. The lane's state record
+// takes the stream's launch instant as its own, so `run:board`, which reads the lane's events from
+// the record's launch on, keeps the launch event that opens them (joshuafolkken/kit#4269).
+async function record_started(issue: string, start: DispatchStart): Promise<void> {
+	const now = new Date()
+
 	await run_event_stream_emit.emit(
 		run_event_stream.EVENT_KIND.CHILD_LAUNCH,
 		`${issue_cite.plain(issue)} dispatched`,
+		now,
 	)
 	await lane_ledger.record_dispatch(Number(issue))
+	await lane_state.record_change(
+		{
+			issue,
+			state: 'running',
+			command: start === RESTART_START ? 'lane:restart' : 'lane:dispatch',
+			is_launch: true,
+		},
+		{ now },
+	)
 }
 
 // How a dispatch begins. A `resumable` one claims the marker itself and resumes an `outage` session; a
@@ -359,7 +380,7 @@ async function finish_dispatch(
 
 	const is_failed = outcome.kind === 'failed'
 
-	await (is_failed ? run_label.unmark(issue) : record_started(issue))
+	await (is_failed ? run_label.unmark(issue) : record_started(issue, start))
 
 	return outcome
 }
@@ -404,7 +425,7 @@ function log_sentence(outcome: Dispatched, issue: string): string {
 		return ` Its output is NOT being kept — ${outcome.notes.join(NOTE_SEPARATOR)} — so ${outcome.log_path} will not grow and the process trace is the only answer: ${poll}.`
 	}
 
-	return ` It writes to ${outcome.log_path}. To poll it, ${poll}.`
+	return ` It writes to ${outcome.log_path}. Wait on it with \`pnpm josh lane:await ${issue} --owner "$PPID"\` in the background and end the turn; once that output falls silent, ${poll}.`
 }
 
 // Whether this dispatch resumed the disconnected child's session or started fresh — the report the

package/scripts/lane/lane-gap-stats.ts

@@ -0,0 +1,156 @@
+import { agent_role_profile } from '#scripts/agent/agent-role-profile'
+import { MS_PER_SECOND } from '#scripts/lib/timeouts'
+import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-stream'
+import { lane_ledger, type LedgerEntry, type MergeEntry } from './lane-ledger'
+import { lane_spans, type Span } from './lane-spans'
+import { lane_stage_stats } from './lane-stage-stats'
+import { lane_stats, type StatsWindow } from './lane-stats'
+import { lane_stop_stats } from './lane-stop-stats'
+
+// How long a lane slot waited on the lane machinery rather than on work, printed by `josh lane:stats`
+// (joshuafolkken/kit#4395). Three hand-offs, each timed from the moment the slot's next step could run:
+//
+// - `cut → resume`: a child's session cut until the relaunched session resumed the lane.
+// - `outage → relaunch`: a child that ended with no result, collected as an `outage`, until its next
+//   `child-launch` (joshuafolkken/kit#4410).
+// - `park → offer`: a park until the driver's next offer answered — a `held`, `released` or `dispatch`
+//   entry. A pool that stays full writes no line after its one `released`, and a driver handed back
+//   writes none, so a gap over the offer interval is a full pool or no driver, never the hand-over
+//   (joshuafolkken/kit#4410). The ship's cap park and the driver's collection of it are each timed.
+// - `followup → merge`: the ship's last `followup` stage before the merge until the parent wrote the
+//   `merge` line, the step that releases the slot. A merge with no `followup` stage has no start.
+//
+// A start nothing ended is counted under `not ended`, kept out of the seconds.
+
+const COLUMNS = ['gap', 'count', 'median (s)', 'max (s)', 'not ended'] as const
+const RELAUNCH = 'cut → resume'
+const OUTAGE = 'outage → relaunch'
+const PARK = 'park → offer'
+const MERGE = 'followup → merge'
+const FOLLOWUP_STAGE = 'followup'
+const IMPLEMENTATION_CUT = `cut (${agent_role_profile.IMPLEMENTATION_PHASE})`
+const { NOT_MEASURED, is_dispatch, is_number, is_stage } = lane_stage_stats
+const { EVENT_KIND } = run_event_stream
+// The offer answers that are not a dispatch: a free lane held, or the pool found full.
+const OFFER_ANSWERS: ReadonlySet<string> = new Set([
+	lane_ledger.KIND.HELD,
+	lane_ledger.KIND.RELEASED,
+])
+
+// Only an implementation cut appends a `resume` when it is adopted; a pre-gate resume appends nothing,
+// so its cut would read as never ended (`run-cut-cli.ts` → `emit_resume_event`).
+function implementation_cuts(events: ReadonlyArray<RunEvent>): Array<RunEvent> {
+	return events.filter((event) => event.text.endsWith(IMPLEMENTATION_CUT))
+}
+
+function relaunch_spans(events: ReadonlyArray<RunEvent>): Array<Span> {
+	return lane_spans.issue_spans({
+		starts: lane_stop_stats.events_of(implementation_cuts(events), EVENT_KIND.CUT),
+		bounds: lane_stop_stats.events_of(events, EVENT_KIND.CUT),
+		ends: lane_stop_stats.events_of(events, EVENT_KIND.RESUME),
+	})
+}
+
+// A child that ended with no result is collected as an `outage`, re-dispatchable; its next launch is
+// the relaunch.
+function outage_spans(events: ReadonlyArray<RunEvent>): Array<Span> {
+	const outages = lane_stop_stats.events_of(events, EVENT_KIND.OUTAGE)
+
+	return lane_spans.issue_spans({
+		starts: outages,
+		bounds: outages,
+		ends: lane_stop_stats.events_of(events, EVENT_KIND.CHILD_LAUNCH),
+	})
+}
+
+function offer_times(entries: ReadonlyArray<LedgerEntry>): Array<number> {
+	return entries
+		.filter((entry) => is_dispatch(entry) || OFFER_ANSWERS.has(entry.kind))
+		.map((entry) => Date.parse(entry.at))
+		.toSorted((left, right) => left - right)
+}
+
+function park_spans(
+	entries: ReadonlyArray<LedgerEntry>,
+	events: ReadonlyArray<RunEvent>,
+): Array<Span> {
+	const offers = offer_times(entries)
+
+	return lane_stop_stats
+		.events_of(events, EVENT_KIND.PARK)
+		.map((park) => ({ from_ms: park.at_ms, end_ms: offers.find((at) => at > park.at_ms) }))
+}
+
+function is_merge(entry: LedgerEntry): entry is MergeEntry {
+	return entry.kind === lane_ledger.KIND.MERGE
+}
+
+function is_followup_of(entry: LedgerEntry, merge: MergeEntry): boolean {
+	return (
+		is_stage(entry) &&
+		entry.stage === FOLLOWUP_STAGE &&
+		entry.issue === merge.issue &&
+		entry.at <= merge.at
+	)
+}
+
+function merge_span(entries: ReadonlyArray<LedgerEntry>, merge: MergeEntry): Span | undefined {
+	const followup = entries.findLast((entry) => is_followup_of(entry, merge))
+
+	return followup === undefined
+		? undefined
+		: { from_ms: Date.parse(followup.at), end_ms: Date.parse(merge.at) }
+}
+
+function merge_spans(entries: ReadonlyArray<LedgerEntry>): Array<Span> {
+	return entries
+		.filter((entry) => is_merge(entry))
+		.map((merge) => merge_span(entries, merge))
+		.filter((span) => span !== undefined)
+}
+
+function seconds(milliseconds: number | undefined): string {
+	return milliseconds === undefined
+		? NOT_MEASURED
+		: String(Math.round(milliseconds / MS_PER_SECOND))
+}
+
+function is_in(span: Span, window: StatsWindow): boolean {
+	return span.from_ms >= window.since_ms && span.from_ms <= window.until_ms
+}
+
+function gap_row(name: string, spans: ReadonlyArray<Span>, window: StatsWindow): string {
+	const started = spans.filter((span) => is_in(span, window))
+	const ended = started
+		.map((span) => (span.end_ms === undefined ? undefined : span.end_ms - span.from_ms))
+		.filter((value) => is_number(value))
+
+	return lane_stats.to_row([
+		name,
+		String(started.length),
+		seconds(lane_stats.median(ended)),
+		seconds(lane_stats.peak(ended)),
+		String(started.length - ended.length),
+	])
+}
+
+// The period's table: `entries` is the whole ledger and `events` the whole run-event stream, both
+// reduced here to the spans that started in `window`.
+function table(
+	entries: ReadonlyArray<LedgerEntry>,
+	window: StatsWindow,
+	events: ReadonlyArray<RunEvent> = [],
+): string {
+	return [
+		lane_stats.to_row(COLUMNS),
+		lane_stats.to_row(COLUMNS.map(() => '---')),
+		gap_row(RELAUNCH, relaunch_spans(events), window),
+		gap_row(OUTAGE, outage_spans(events), window),
+		gap_row(PARK, park_spans(entries, events), window),
+		gap_row(MERGE, merge_spans(entries), window),
+	].join('\n')
+}
+
+const lane_gap_stats = { table }
+
+export { lane_gap_stats }

package/scripts/lane/lane-guard-policy.ts

@@ -45,9 +45,9 @@ interface LaneGuardEntry {
 const LANE_GUARD_POLICY: ReadonlyArray<LaneGuardEntry> = [
 	{
 		id: 'investigation',
-		mode_in_lane_child: 'notice',
+		mode_in_lane_child: 'refuse',
 		because:
-			'a refusal ends a child turn, yet lane children were measured reading files they never edited, so the child is nudged to delegate by a notice rather than killed',
+			'the notice was measured not to move the reading — 52% of lane cost stayed in main-line exploration — and the refusal fires once per accumulation, a round trip the child survives as it survives the rule row, so the child is refused like the main line',
 	},
 	{
 		id: 'batching',

package/scripts/lane/lane-handoff.ts

@@ -1,7 +1,11 @@
 import { git_common_directory } from '#scripts/git/git-common-directory'
+import { run_carry } from '#scripts/run/carry/run-carry'
 import { run_ship_detach } from '#scripts/run/ship/run-ship-detach'
+import { run_ship_stage } from '#scripts/run/ship/run-ship-stage'
 import { lane_child_marker, type MarkerSource } from './lane-child-marker'
 
+type StartRead = (pid: number) => string | undefined
+
 // Whether a lane has handed its post-implementation region to the detached ship.
 //
 // **A child that ran `pnpm josh ship --detach` waits on nobody when it ends.** The supervisor drives the
@@ -24,6 +28,69 @@ function is_ship_running(issue: string, directory: string): boolean {
 	)
 }
 
+// A detached ship for `issue` launched at or after `since_ms` ended in success — it merged, so no cut
+// hand-off follows it. The record outlives its run until the next `ship --detach` replaces it, so a
+// success launched earlier belongs to a past dispatch of the issue and never counts.
+function is_ship_succeeded(issue: string, directory: string, since_ms: number): boolean {
+	const repository = git_common_directory.repository(directory)
+	const reading =
+		repository === undefined ? undefined : run_ship_detach.read_result(repository, issue)
+
+	return reading?.result === 'success' && (reading.launched_at ?? since_ms - 1) >= since_ms
+}
+
+async function read_repository(): Promise<string | undefined> {
+	try {
+		return await run_carry.repository_directory()
+	} catch {
+		return undefined
+	}
+}
+
+// `is_ship_running` for this checkout, for a reader that must not block its event loop
+// (joshuafolkken/kit#4245): the repository is read asynchronously once and every recorded start time
+// through `read`, so no answer starts a synchronous process.
+async function ship_reader(read: StartRead): Promise<(issue: string) => boolean> {
+	const repository = await read_repository()
+
+	return (issue) =>
+		repository !== undefined &&
+		run_ship_detach.read_result(repository, issue, read)?.result === 'running'
+}
+
+// The live ship for `issue` is inside `josh followup`: it waits on CI, CodeRabbit and the merge alone
+// (joshuafolkken/kit#4466). The mark is down while the followup stage merges and gates again, after a
+// stop, and once a successor supervisor opens the record (`run_ship_stage.read_merge_waiting`).
+function is_merge_waiting(repository: string, issue: string, read: StartRead): boolean {
+	if (run_ship_detach.read_result(repository, issue, read)?.result !== 'running') return false
+
+	return run_ship_stage.read_merge_waiting(run_ship_stage.record_path(repository, issue))
+}
+
+// `is_merge_waiting` for this checkout, read the way `ship_reader` reads.
+async function merge_wait_reader(read: StartRead): Promise<(issue: string) => boolean> {
+	const repository = await read_repository()
+
+	return (issue) => repository !== undefined && is_merge_waiting(repository, issue, read)
+}
+
+// The live ship for `issue` in the repository `directory` belongs to waits for a lane place before it
+// relaunches its child (`run-ship-place.ts`); a dead supervisor's mark reads as no wait.
+function is_place_waiting(issue: string, directory: string): boolean {
+	const repository = git_common_directory.repository(directory)
+
+	if (repository === undefined || !is_ship_running(issue, directory)) return false
+
+	return run_ship_stage.read_place_waiting(run_ship_stage.record_path(repository, issue))
+}
+
+// When the detached ship for `issue` that is still live was launched, or `undefined` where none is.
+function ship_running_since(issue: string, directory: string): number | undefined {
+	const repository = git_common_directory.repository(directory)
+
+	return repository === undefined ? undefined : run_ship_detach.running_since(repository, issue)
+}
+
 // This session is the dispatched lane child for `directory` and its own ship is running.
 function is_handed_off(directory: string, source: MarkerSource = process.env): boolean {
 	const issue = lane_child_marker.marked_issue(source)
@@ -33,6 +100,14 @@ function is_handed_off(directory: string, source: MarkerSource = process.env): b
 	return is_ship_running(issue, directory)
 }
 
-const lane_handoff = { is_handed_off, is_ship_running }
+const lane_handoff = {
+	is_handed_off,
+	is_place_waiting,
+	is_ship_running,
+	is_ship_succeeded,
+	merge_wait_reader,
+	ship_reader,
+	ship_running_since,
+}
 
 export { lane_handoff }