@joshuafolkken/kit 1.1471.0 → 1.1784.0

package/scripts/lane/lane-registry.ts

@@ -1,4 +1,4 @@
-import { existsSync } from 'node:fs'
+import { existsSync, statSync } from 'node:fs'
 import path from 'node:path'
 import { ENV_FILE_NAME } from '#ports'
 import type { AgentProfile } from '#scripts/agent/agent-role-profile'
@@ -38,6 +38,9 @@ interface LaneInfo {
 	// instead of waiting for the pool to drain before it can be cut.
 	output: string | undefined
 	profile?: AgentProfile | undefined
+	// When the lane last took a child: `lane:open` writes its `.env`, and every dispatch records its
+	// unit there (`lane-output.ts`). `undefined` where the `.env` cannot be read.
+	dispatched_ms?: number | undefined
 	is_stranded: boolean
 }
 
@@ -106,6 +109,10 @@ function read_environment(directory: string): string | undefined {
 	return file_reader.read_if_readable(path.join(directory, ENV_FILE_NAME))
 }
 
+function dispatched_at(directory: string): number | undefined {
+	return statSync(path.join(directory, ENV_FILE_NAME), { throwIfNoEntry: false })?.mtimeMs
+}
+
 // A lane is identified by its branch rather than by where it sits, so nothing here compares two
 // spellings of one path — git prints the resolved one, and a lane root reached through a symlink
 // would otherwise read as no lane at all.
@@ -151,6 +158,7 @@ function build_lane(
 		preview_port: held.preview_port,
 		output,
 		profile,
+		dispatched_ms: is_stranded ? undefined : dispatched_at(directory),
 		is_stranded,
 	}
 }
@@ -214,9 +222,28 @@ async function main_repository_root(): Promise<string> {
 	return repo_discovery.main_worktree(await git_command.repository_root())
 }
 
-/** Every open lane of this repository, lowest issue number first. */
-async function list_lanes(): Promise<Array<LaneInfo>> {
-	const root = lane_paths.lane_root(await main_repository_root())
+/**
+ * The directory this repository's lanes live in, read from the main work tree rather than this one —
+ * derived from the current work tree, a command run inside a lane would look for lanes inside it.
+ */
+async function lane_root_directory(): Promise<string> {
+	return lane_paths.lane_root(await main_repository_root())
+}
+
+/**
+ * The issue's lane by the directory its number implies, registered or not — what ending its processes
+ * needs (`lane_reap.reap_child`), so a lane `list_lanes` no longer reads is still reached.
+ */
+async function lane_location(issue: string): Promise<Pick<LaneInfo, 'issue' | 'directory'>> {
+	return { issue, directory: lane_paths.lane_directory(await lane_root_directory(), issue) }
+}
+
+/**
+ * Every open lane of this repository, lowest issue number first. `main_root` is the main work tree a
+ * caller already resolved — `run:board` resolves it once rather than with a `git` call each read.
+ */
+async function list_lanes(main_root?: string): Promise<Array<LaneInfo>> {
+	const root = lane_paths.lane_root(main_root ?? (await main_repository_root()))
 	const blocks = await worktree_blocks()
 	const lanes = blocks.map((block) => parse_block(block, root)).filter(is_lane)
 
@@ -241,11 +268,6 @@ async function has_lanes_in_flight(): Promise<boolean> {
 	return lanes.some((lane) => !lane.is_stranded)
 }
 
-/** The lanes in use: the open work trees an interruption has not stranded. */
-function live_count(lanes: ReadonlyArray<LaneInfo>): number {
-	return lanes.filter((lane) => !lane.is_stranded).length
-}
-
 /** The seats live lanes hold — what a new lane's seat has to avoid. */
 function used_seats(lanes: ReadonlyArray<LaneInfo>): Array<number> {
 	return lanes.map((lane) => lane.seat).filter((seat): seat is number => seat !== undefined)
@@ -276,8 +298,9 @@ const lane_registry = {
 	find_lane,
 	find_open_lane,
 	has_lanes_in_flight,
+	lane_location,
+	lane_root_directory,
 	list_lanes,
-	live_count,
 	main_repository_root,
 	parse_block,
 	read_environment,

package/scripts/lane/lane-residents.ts

@@ -0,0 +1,162 @@
+import { spawnSync } from 'node:child_process'
+import path from 'node:path'
+import { PROBE_TIMEOUT_MS } from '#scripts/lib/timeouts'
+import { lane_reap } from './lane-reap'
+import { process_directories } from './process-directories'
+import { process_lane_marks } from './process-lane-marks'
+
+// Ending what still runs from a lane's checkout, or carries its mark, when the lane closes
+// (joshuafolkken/kit#4304, joshuafolkken/kit#4315).
+//
+// **The lane child's tree and its `eslint_d` are not everything a lane starts.** A diagnostic the
+// child launched under `script`, or a `node` it detached, is re-parented to pid 1 and outlives the
+// merge: no tree reaches it and no title names it, and `run:board` drew such processes as a leftover
+// holding gigabytes while nothing ended them. Its working directory still sits under the lane, which
+// is what finds it — the same reading the board's leftover is drawn from (`process-directories.ts`).
+// **A process the child started from elsewhere** — a measurement run from the main checkout or `/tmp`
+// — has no such directory, so the lane's mark it inherited finds it instead (`process-lane-marks.ts`):
+// the issue number `lane:dispatch` put in the child's environment. A process without the mark, or with
+// another issue's, is never this lane's.
+//
+// **Only that lane's processes, and never the caller.** Another lane's and the main checkout's
+// unmarked processes are not its. A `lane:close` run from inside the lane would match itself, so its
+// ancestry is spared, as `lane-reap.ts` spares it — and so is its process group: its own helpers
+// (`tsx`'s `esbuild`) and the commands piped beside it share the group, while a detached process
+// (`script`, a new session) has left it.
+
+const GROUP_ARGUMENTS = ['-o', 'pid=,pgid=', '-p']
+const PID_SEPARATOR = ','
+// `ps`'s line: the process and its group.
+const PAIR_LENGTH = 2
+
+interface ResidentLane {
+	issue: string
+	directory: string
+}
+
+interface ResidentProbes {
+	// `undefined` where the working directories could not be read.
+	directories: () => ReadonlyMap<number, string> | undefined
+	// Each marked process's issue; `undefined` where the marks could not be read.
+	marks: () => ReadonlyMap<number, string> | undefined
+	own: () => ReadonlySet<number>
+	// Each listed process's group; a process gone by then is missing.
+	groups_of: (pids: ReadonlyArray<number>) => ReadonlyMap<number, number>
+	terminate: (pid: number) => boolean
+}
+
+function parse_groups(printed: string): Map<number, number> {
+	const pairs = printed
+		.split('\n')
+		.map((line) => line.trim().split(/\s+/u).map(Number))
+		.filter((pair) => pair.length === PAIR_LENGTH && pair.every((id) => Number.isSafeInteger(id)))
+
+	return new Map(pairs.map(([pid = 0, group = 0]) => [pid, group] as const))
+}
+
+// `ps` exits non-zero when a listed process is gone and still prints the rest, so its output is read
+// whatever the exit status.
+function groups_of(pids: ReadonlyArray<number>): Map<number, number> {
+	const result = spawnSync(lane_reap.PS_COMMAND, [...GROUP_ARGUMENTS, pids.join(PID_SEPARATOR)], {
+		encoding: 'utf8',
+		timeout: PROBE_TIMEOUT_MS,
+		stdio: ['ignore', 'pipe', 'ignore'],
+	})
+
+	return parse_groups(result.stdout)
+}
+
+const SYSTEM_PROBES: ResidentProbes = {
+	directories: () => process_directories.list_all(),
+	marks: () => process_lane_marks.list_all(),
+	own: () => lane_reap.own_ancestry(),
+	groups_of,
+	terminate: (pid) => lane_reap.SYSTEM_PROBES.terminate(pid),
+}
+
+// The candidates outside the caller's process group. The caller's own group unread spares nothing
+// more: its ancestry is spared regardless.
+function outside_own_group(candidates: Array<number>, probes: ResidentProbes): Array<number> {
+	if (candidates.length === 0) return candidates
+	const groups = probes.groups_of([process.pid, ...candidates])
+	const own_group = groups.get(process.pid)
+
+	return candidates.filter((pid) => own_group === undefined || groups.get(pid) !== own_group)
+}
+
+// Every process running from the lane's directory or carrying its mark, once each.
+function lane_processes(
+	lane: ResidentLane,
+	directories: ReadonlyMap<number, string>,
+	marks: ReadonlyMap<number, string>,
+): Array<number> {
+	const root = path.dirname(lane.directory)
+	const within = [...directories]
+		.filter(([, cwd]) => process_directories.lane_of(cwd, root) === lane.issue)
+		.map(([pid]) => pid)
+	const marked = [...marks].filter(([, issue]) => issue === lane.issue).map(([pid]) => pid)
+
+	return [...new Set([...within, ...marked])]
+}
+
+/**
+ * The processes running from `lane`'s directory or carrying its mark, the caller's ancestry and process
+ * group left out; `undefined` where the working directories or the marks could not be read.
+ */
+function residents(
+	lane: ResidentLane,
+	probes: ResidentProbes = SYSTEM_PROBES,
+): Array<number> | undefined {
+	const directories = probes.directories()
+	const marks = probes.marks()
+
+	if (directories === undefined || marks === undefined) return undefined
+	const own = probes.own()
+	const candidates = lane_processes(lane, directories, marks).filter((pid) => !own.has(pid))
+
+	return outside_own_group(candidates, probes)
+}
+
+/**
+ * Terminate the processes still running from `lane`'s directory or carrying its mark, except `spared`
+ * — what the close already ended. Returns the pids the signal reached, `undefined` where they could
+ * not be read.
+ */
+function end_residents(
+	lane: ResidentLane,
+	spared: ReadonlyArray<number>,
+	probes: ResidentProbes = SYSTEM_PROBES,
+): Array<number> | undefined {
+	return residents(lane, probes)
+		?.filter((pid) => !spared.includes(pid))
+		.filter((pid) => probes.terminate(pid))
+}
+
+/**
+ * What `end_residents` did, said for the issue `cited`; `undefined` when nothing of the lane still ran.
+ * A reading that failed is said, never read as none.
+ */
+function residents_sentence(
+	ended: ReadonlyArray<number> | undefined,
+	cited: string,
+): string | undefined {
+	if (ended === undefined) {
+		return `Could not read which processes still run from the lane for ${cited} (lsof or ps failed); none of them was ended.`
+	}
+
+	if (ended.length === 0) return undefined
+
+	return `Terminated ${String(ended.length)} process(es) still running from the lane for ${cited}: ${ended.join(', ')}.`
+}
+
+/** Print `residents_sentence` to stderr, where a close reports what it ended. */
+function report(ended: ReadonlyArray<number> | undefined, cited: string): void {
+	const sentence = residents_sentence(ended, cited)
+
+	if (sentence !== undefined) console.error(sentence)
+}
+
+const lane_residents = { end_residents, parse_groups, report, residents, residents_sentence }
+
+export type { ResidentLane, ResidentProbes }
+export { lane_residents }

package/scripts/lane/lane-restart.ts

@@ -3,21 +3,21 @@ import { issue_cite } from '#scripts/issue/issue-cite'
 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 { error_text } from '#scripts/lib/error-message'
 import { run_cut } from '#scripts/run/cut/run-cut'
 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 { lane_dispatch, type DispatchOutcome } from './lane-dispatch'
-import { lane_preserve } from './lane-preserve'
+import { lane_preserve, type KeptWork } from './lane-preserve'
 import { lane_reap } from './lane-reap'
 import { lane_registry, type LaneInfo } from './lane-registry'
+import { lane_residents } from './lane-residents'
 
 // `josh lane:restart <N>` — a person stops a running lane child and starts its issue over in a fresh
 // session, typically after correcting the Issue's specification mid-run.
 //
 // **The restart is a hand-off inside the parent's re-confirm window, not a recovery.** Killing the child
 // alone would let `lane:await` book it stopped and `run:merge` classify it — an `outage` resumes the old
-// session with the old specification in mind, anything else is parked `needs-decision` and counted as a
+// session with the old specification in mind, anything else is parked `run:stalled` and counted as a
 // failure. `run:cut` already hands a lane to a new process inside `lane:await`'s re-confirm window, so a
 // child that disappears and reappears under the same `fullrun #<N>` pattern is never collected: the
 // restart stops, stashes and re-dispatches within that window, and no failure or outage is counted.
@@ -37,12 +37,9 @@ const DISPATCHED_KIND = 'dispatched'
 const NO_LANE_KIND = 'no-lane'
 const NOT_RUNNING_KIND = 'not-running'
 const UNCLAIMED_KIND = 'unclaimed'
+const CONFLICTED_KIND = 'conflicted'
 
-interface Unsaved {
-	kind: 'unsaved'
-	directory: string
-	reason: string
-}
+type Unsaved = Extract<KeptWork, { kind: 'unsaved' }>
 
 interface Restarted {
 	kind: 'restarted'
@@ -54,8 +51,8 @@ type Refused =
 	| { kind: typeof NO_LANE_KIND }
 	| { kind: typeof NOT_RUNNING_KIND }
 	| { kind: typeof UNCLAIMED_KIND; reason: string }
+	| { kind: typeof CONFLICTED_KIND; directory: string }
 type RestartOutcome = Restarted | Unsaved | Refused
-type Saved = Unsaved | { kind: 'saved'; stash: string | undefined }
 
 // A cut the stopped child carried would hand its successor the old session's hand-off at
 // `run:cut --resume`; the fresh session has to start from the Issue instead.
@@ -65,22 +62,6 @@ function end_carried_cut(lane: LaneInfo): void {
 	if (carried !== undefined) run_cut.end_cut(carried.target)
 }
 
-async function stash_of(lane: LaneInfo): Promise<string | undefined> {
-	if (!(await git_stash.has_changes(lane.directory))) return undefined
-
-	return await lane_preserve.push_work(lane.issue, lane.directory, RESTART_OCCASION)
-}
-
-// A tree that could not be read or pushed is left as it is: re-dispatching into it would hand the fresh
-// session the stopped one's half-done work as though it were its own.
-async function save_work(lane: LaneInfo): Promise<Saved> {
-	try {
-		return { kind: 'saved', stash: await stash_of(lane) }
-	} catch (error) {
-		return { kind: 'unsaved', directory: lane.directory, reason: error_text.message_of(error) }
-	}
-}
-
 async function record_restart(issue: string): Promise<void> {
 	await run_event_stream_emit.emit(
 		run_event_stream.EVENT_KIND.RESTART,
@@ -88,9 +69,11 @@ async function record_restart(issue: string): Promise<void> {
 	)
 }
 
+// A tree that could not be read or pushed is left as it is: re-dispatching into it would hand the fresh
+// session the stopped one's half-done work as though it were its own.
 async function relaunch(lane: LaneInfo): Promise<RestartOutcome> {
 	end_carried_cut(lane)
-	const saved = await save_work(lane)
+	const saved = await lane_preserve.keep_work(lane.issue, lane.directory, RESTART_OCCASION)
 
 	if (saved.kind === 'unsaved') return saved
 	const dispatch = await lane_dispatch.dispatch_child(lane.issue, 'restart')
@@ -106,12 +89,19 @@ async function relaunch(lane: LaneInfo): Promise<RestartOutcome> {
 
 // A child that ended on its own during the claim (say, right after merging its PR) is a finished child
 // for `run:merge` to collect — relaunching it would re-run a done issue inside the re-confirm window.
+// What the stopped child started outside its tree goes with it, so the fresh session starts beside none
+// of it (`lane-residents.ts`).
 async function stop_and_relaunch(lane: LaneInfo): Promise<RestartOutcome> {
-	if (lane_reap.reap_child(lane.issue).length === 0) return { kind: NOT_RUNNING_KIND }
+	const reaped = lane_reap.reap_child(lane)
+
+	if (reaped.length === 0) return { kind: NOT_RUNNING_KIND }
+	lane_residents.report(lane_residents.end_residents(lane, reaped), session_cite.issue(lane.issue))
 
 	return await relaunch(lane)
 }
 
+// A tree with unresolved conflicts (a sync's merge stopped mid-way) cannot be stashed, so it is refused
+// before the stop — stopping first would strand the lane with no child and nothing re-dispatched.
 /** Stop the running child of `#<N>`'s lane and re-dispatch the issue there in a fresh session. */
 async function restart(issue: string): Promise<RestartOutcome> {
 	issue_number_shape.require_issue_number(issue)
@@ -119,6 +109,11 @@ async function restart(issue: string): Promise<RestartOutcome> {
 
 	if (lane === undefined) return { kind: NO_LANE_KIND }
 	if (!lane_reap.is_child_running(issue)) return { kind: NOT_RUNNING_KIND }
+
+	if (await git_stash.has_conflict(lane.directory)) {
+		return { kind: CONFLICTED_KIND, directory: lane.directory }
+	}
+
 	const claim = await lane_dispatch.claim_marker(issue)
 
 	if (!claim.is_applied) return { kind: UNCLAIMED_KIND, reason: claim.reason }
@@ -154,6 +149,10 @@ function refused_text(outcome: Refused, issue: string): string {
 		return `No lane is open for ${cited}, so there is no child to restart.`
 	}
 
+	if (outcome.kind === CONFLICTED_KIND) {
+		return `The lane for ${cited} has unresolved conflicts, which \`git stash\` cannot keep, so the running child was left as it is — nothing was stopped or re-dispatched. Resolve them, or run \`git -C ${outcome.directory} merge --abort\`, then run \`pnpm josh lane:restart ${issue}\` again.`
+	}
+
 	if (outcome.kind === UNCLAIMED_KIND) {
 		return `The \`${IN_PROGRESS_LABEL}\` label could not be confirmed on ${cited} (${outcome.reason}), so the running child was left as it is — nothing was stopped or re-dispatched.`
 	}

package/scripts/lane/lane-round-two-stats.ts

@@ -0,0 +1,49 @@
+import { lane_ledger, type LedgerEntry, type RoundTwoEntry } from './lane-ledger'
+import { lane_stats, type StatsWindow } from './lane-stats'
+
+// Why round 2 ran or was skipped: the ledger's `round-two` entries of one period reduced to one row per
+// verdict and reason code, printed by `josh lane:stats` so the next change — to the procedure, or to
+// what counts as an inert fix — is chosen from counts rather than impressions (joshuafolkken/kit#4064).
+
+const COLUMNS = ['round 2', 'code', 'decisions'] as const
+const KEY_SEPARATOR = ' '
+// A period with no decision: the table still prints, so a reader sees zero rather than no table.
+const NONE_ROW = ['none', 'none', '0']
+
+function is_round_two(entry: LedgerEntry): entry is RoundTwoEntry {
+	return entry.kind === lane_ledger.KIND.ROUND_TWO
+}
+
+function counts_of(decisions: ReadonlyArray<RoundTwoEntry>): Map<string, number> {
+	const counts = new Map<string, number>()
+
+	for (const decision of decisions) {
+		const key = `${decision.verdict}${KEY_SEPARATOR}${decision.code}`
+
+		counts.set(key, (counts.get(key) ?? 0) + 1)
+	}
+
+	return counts
+}
+
+// The most frequent pair first, so the reason worth acting on leads.
+function rows_of(counts: ReadonlyMap<string, number>): Array<string> {
+	return [...counts]
+		.toSorted(([, left], [, right]) => right - left)
+		.map(([key, count]) => lane_stats.to_row([...key.split(KEY_SEPARATOR), String(count)]))
+}
+
+// The period's table: `entries` is the whole ledger, filtered here to `window`.
+function table(entries: ReadonlyArray<LedgerEntry>, window: StatsWindow): string {
+	const rows = rows_of(counts_of(lane_stats.in_window(entries, window).filter(is_round_two)))
+
+	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_round_two_stats = { table }
+
+export { lane_round_two_stats }

package/scripts/lane/lane-sampler.ts

@@ -14,6 +14,10 @@ const SAMPLE_INTERVAL_MS = 60_000
 // Where the ledger is and what "now" is, overridable so a test reads a fixed ledger at a fixed instant.
 interface MeasureContext {
 	ledger_path?: string
+	// The run's event stream `lane:stats` reads parks from; absent, the repository's own.
+	events_path?: string
+	// The lane transcript directories `lane:stats` reads tool calls from; absent, this repository's lanes'.
+	transcript_directories?: ReadonlyArray<string>
 	now_ms?: number
 }
 

package/scripts/lane/lane-session-action.ts

@@ -0,0 +1,160 @@
+import { agent_argv } from '#scripts/agent/agent-argv'
+import { agent_role_profile, type AgentProvider } from '#scripts/agent/agent-role-profile'
+import { api_auth } from '#scripts/agent/api-auth'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { error_text } from '#scripts/lib/error-message'
+import { detached_launch, type AttachedLaunchResult } from '#scripts/run/detached-launch'
+import { run_ship_review } from '#scripts/run/ship/run-ship-review'
+import { run_ship_stage } from '#scripts/run/ship/run-ship-stage'
+import { run_ship_stop_cause } from '#scripts/run/ship/run-ship-stop-cause'
+import { run_ship_stop_context } from '#scripts/run/ship/run-ship-stop-context'
+import { z } from 'zod'
+import { lane_child_invocation, type ShipStop } from './lane-child-invocation'
+import { lane_child_marker } from './lane-child-marker'
+import { lane_parked } from './lane-parked'
+import type { LaneInfo } from './lane-registry'
+import { lane_relaunch } from './lane-relaunch'
+
+// The actions a lane's session broker performs for the ship that asked (`lane-session-broker.ts`):
+// starting the round-1 or round-2 reviewer, or relaunching the lane's child after a stopped ship.
+// **A failure names its reason**: a bare `false` left every relaunch a stale supervisor refused
+// unexplained in the ship log (joshuafolkken/kit#3974).
+
+const BRIEF_PREFIX = 'josh-ship-review-brief-'
+const FINDINGS_PREFIX = 'josh-ship-review-findings-'
+const LOG_PREFIX = 'josh-ship-review-log-'
+const ANTHROPIC_PROVIDER: AgentProvider = 'anthropic'
+const stop_schema = z
+	.object({
+		stage: z.enum(run_ship_stage.STAGE),
+		title: z.string(),
+		flags: z.array(z.string()).readonly(),
+		is_review: z.boolean(),
+		conflicts: z.array(z.string()).readonly().default([]),
+		cause: z.enum(run_ship_stop_cause.CAUSE).exactOptional(),
+		is_review_stale: z.boolean().exactOptional(),
+		context: run_ship_stop_context.stop_context_schema.exactOptional(),
+	})
+	.strict()
+const action_schema = z.discriminatedUnion('kind', [
+	z.object({ kind: z.literal('review'), round: z.enum(['1', '2']) }).strict(),
+	z.object({ kind: z.literal('relaunch'), stop: stop_schema }).strict(),
+])
+type ReviewRound = Extract<z.infer<typeof action_schema>, { kind: 'review' }>['round']
+type BrokerAction = { kind: 'review'; round: ReviewRound } | { kind: 'relaunch'; stop: ShipStop }
+type BrokerAnswer = { is_success: true } | { is_success: false; reason: string }
+
+const SUCCESS: BrokerAnswer = { is_success: true }
+
+function failure(reason: string): BrokerAnswer {
+	return { is_success: false, reason }
+}
+
+function review_paths(directory: string): { brief: string; findings: string; log: string } {
+	return {
+		brief: stamp_file.stamp_path(BRIEF_PREFIX, directory, '.md'),
+		findings: stamp_file.stamp_path(FINDINGS_PREFIX, directory, '.txt'),
+		log: stamp_file.stamp_path(LOG_PREFIX, directory, '.log'),
+	}
+}
+
+// The reviewer runs on the lane's own provider, so a Claude lane's server never starts a Codex reviewer
+// and an OpenAI lane's never starts a Claude one.
+function provider_of(lane: LaneInfo): AgentProvider {
+	return lane.profile?.provider ?? ANTHROPIC_PROVIDER
+}
+
+// **The reviewer carries the lane's mark explicitly**: the supervisor serving a Claude lane is no lane child,
+// so a reviewer inheriting its environment would descend from the carry record's owner unmarked and be
+// read as the `backlogrun` parent by every hook. **Its prompt ends with the review invocation**, so the
+// lane's liveness read and the park's reap find it as they find the child (joshuafolkken/kit#3878).
+
+function review_prompt(lane: LaneInfo, round: ReviewRound): string {
+	const target = review_paths(lane.directory)
+	const prompt_of =
+		round === '1' ? run_ship_review.reviewer_prompt : run_ship_review.verification_prompt
+	const tail = lane_child_invocation.review_invocation(lane.issue)
+
+	return `${prompt_of(target.brief, target.findings, lane.issue)} This is ${tail}`
+}
+
+// **A reviewer that could not authenticate names it** with `api_auth.AUTH_FAILURE_NOTE`, read off its
+// log's exit record, so the ship stop is not booked as a review finding (joshuafolkken/kit#4216).
+function exited_answer(exit_code: number | null, log_path: string): BrokerAnswer {
+	const exited = `the reviewer exited with code ${String(exit_code)}`
+
+	if (!api_auth.is_auth_failed_transcript(stamp_file.read_stamp_text(log_path))) {
+		return failure(exited)
+	}
+
+	return failure(`${api_auth.AUTH_FAILURE_NOTE}: ${exited}`)
+}
+
+function reviewer_answer(result: AttachedLaunchResult, log_path: string): BrokerAnswer {
+	if (result.kind === 'failed') return failure(`the reviewer could not start: ${result.note}`)
+
+	return result.exit_code === 0 ? SUCCESS : exited_answer(result.exit_code, log_path)
+}
+
+async function launch_review(lane: LaneInfo, round: ReviewRound): Promise<BrokerAnswer> {
+	const target = review_paths(lane.directory)
+	const built = agent_argv.review_in(review_prompt(lane, round), Number(round), lane.directory)
+	if (built.kind === 'rejected') return failure(`the reviewer profile was rejected: ${built.note}`)
+
+	if (built.profile.provider !== provider_of(lane)) {
+		return failure(`the reviewer resolved to ${built.profile.provider}, not the lane's provider`)
+	}
+
+	console.error(agent_role_profile.describe_review(Number(round), built.profile))
+	const result = await detached_launch.launch_attached(
+		{
+			argv: built.argv,
+			cwd: lane.directory,
+			log_path: target.log,
+			profile: built.profile,
+			env: lane_child_marker.env_for(lane.issue),
+		},
+		console.error,
+	)
+
+	return reviewer_answer(result, target.log)
+}
+
+// An OpenAI lane's successor is its supervisor's to start, never a relaunch's.
+function relaunch(lane: LaneInfo, stop: ShipStop): BrokerAnswer {
+	if (lane_relaunch.is_openai_lane(lane)) {
+		return failure('an OpenAI lane is relaunched by its own supervisor')
+	}
+
+	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, console.error)
+
+	return result.kind === 'launched'
+		? SUCCESS
+		: failure(`the relaunch did not start: ${result.note}`)
+}
+
+// **A parked issue gets no session**: a request can be read long after it was written, so the park is
+// read when the action runs, never when it was asked for (joshuafolkken/kit#3878).
+async function perform(lane: LaneInfo, action: BrokerAction): Promise<BrokerAnswer> {
+	if (await lane_parked.is_parked(lane.issue)) return failure('the issue is parked')
+
+	if (action.kind === 'relaunch') return relaunch(lane, action.stop)
+
+	return await launch_review(lane, action.round)
+}
+
+// What the server answers: a thrown action is a failure naming its error, never a dead server.
+async function answer(lane: LaneInfo, action: BrokerAction): Promise<BrokerAnswer> {
+	try {
+		return await perform(lane, action)
+	} catch (error) {
+		return failure(`the broker failed: ${error_text.message_of(error)}`)
+	}
+}
+
+const lane_session_action = { SUCCESS, action_schema, answer, failure, review_paths }
+
+export type { BrokerAction, BrokerAnswer, ReviewRound }
+export { lane_session_action }