@joshuafolkken/kit 1.1514.0 → 1.1784.0

package/scripts/lane/lane-reap-settle.ts

@@ -0,0 +1,124 @@
+import { userInfo } from 'node:os'
+import { lane_reap } from './lane-reap'
+import { lane_residents, type ResidentLane } from './lane-residents'
+
+// What a close does about the lane's processes once the SIGTERM went out (joshuafolkken/kit#4300).
+//
+// **A SIGTERM is a request, so the close looks again.** After a grace window the lane's directory is
+// read again; whatever is still there gets a SIGKILL, and after a short wait the directory is read a
+// last time. What survives that is reported, each with why it could — another account owns it, or it
+// is stuck in the kernel — so `lane:close` answers `incomplete` and `run:board` can say what is wrong
+// rather than only that something is left.
+
+// Long enough for a node process to run its exit handlers.
+const GRACE_MS = 3000
+// A SIGKILL is not handled, so what still answers after this is not going to go.
+const KILL_WAIT_MS = 1000
+const KILL_SIGNAL = 'SIGKILL'
+const STATE_FORMAT = ['-o', 'user=,stat=', '-p']
+const FIELD_SEPARATOR = /\s+/u
+const UNREADABLE_TEXT = "the lane's processes (lsof or ps failed)"
+
+interface SettleProbes {
+	// `undefined` where the lane's processes could not be read (`lane_residents.residents`).
+	residents: (lane: ResidentLane) => Array<number> | undefined
+	kill: (pid: number) => boolean
+	wait: (milliseconds: number) => Promise<void>
+	// Why a process outlived the SIGKILL.
+	reason_of: (pid: number) => string
+}
+
+interface Survivor {
+	pid: number
+	reason: string
+}
+
+function kill(pid: number): boolean {
+	try {
+		process.kill(pid, KILL_SIGNAL)
+
+		return true
+	} catch {
+		return false
+	}
+}
+
+async function wait(milliseconds: number): Promise<void> {
+	await new Promise((resolve) => setTimeout(resolve, milliseconds))
+}
+
+// Another account's process is the usual survivor — a SIGKILL from this one is refused; otherwise
+// `ps`'s state says it, `U` for an uninterruptible wait.
+function reason_from(user: string, state: string): string {
+	if (user !== userInfo().username) return `owned by ${user}`
+
+	return `state ${state}`
+}
+
+function reason_of(pid: number): string {
+	const printed = lane_reap.run_probe(lane_reap.PS_COMMAND, [...STATE_FORMAT, String(pid)])
+	const [user = '', state = ''] = printed.trim().split(FIELD_SEPARATOR)
+
+	return user.length === 0 ? 'unreadable' : reason_from(user, state)
+}
+
+const SYSTEM_PROBES: SettleProbes = {
+	residents: (lane) => lane_residents.residents(lane),
+	kill,
+	wait,
+	reason_of,
+}
+
+// A reading that failed is not an empty one.
+function is_empty(reading: ReadonlyArray<number> | undefined): boolean {
+	return reading?.length === 0
+}
+
+async function kill_all(
+	lingering: ReadonlyArray<number> | undefined,
+	probes: SettleProbes,
+): Promise<void> {
+	const targets = lingering ?? []
+
+	for (const pid of targets) probes.kill(pid)
+
+	await probes.wait(KILL_WAIT_MS)
+}
+
+function survivors(lane: ResidentLane, probes: SettleProbes): Array<Survivor> | undefined {
+	return probes.residents(lane)?.map((pid) => ({ pid, reason: probes.reason_of(pid) }))
+}
+
+/**
+ * Wait out the SIGTERM a reap sent, SIGKILL what is still in the lane's directory, and answer what
+ * outlived even that — the empty list is a lane with no process left, `undefined` a last reading that
+ * failed. A failed reading is never read as none: it is read again, and nothing is killed on it.
+ */
+async function settle(
+	lane: ResidentLane,
+	probes: SettleProbes = SYSTEM_PROBES,
+): Promise<Array<Survivor> | undefined> {
+	if (is_empty(probes.residents(lane))) return []
+
+	await probes.wait(GRACE_MS)
+
+	const lingering = probes.residents(lane)
+
+	if (is_empty(lingering)) return []
+
+	await kill_all(lingering, probes)
+
+	return survivors(lane, probes)
+}
+
+/** How a close's `left_behind` names what `settle` answered; a failed reading is named as such. */
+function survivor_texts(settled: ReadonlyArray<Survivor> | undefined): Array<string> {
+	if (settled === undefined) return [UNREADABLE_TEXT]
+
+	return settled.map((survivor) => `process ${String(survivor.pid)} (${survivor.reason})`)
+}
+
+const lane_reap_settle = { GRACE_MS, KILL_WAIT_MS, reason_from, settle, survivor_texts }
+
+export type { SettleProbes, Survivor }
+export { lane_reap_settle }

package/scripts/lane/lane-reap.ts

@@ -18,6 +18,9 @@ import { process_tools } from './process-tools'
 //
 // **The caller's own ancestry is never touched.** A `lane:close` issued from inside the lane it
 // closes would otherwise end the very session running it, before it could report.
+//
+// **What runs from the lane outside the tree is `lane-residents.ts`'s** (joshuafolkken/kit#4300): the
+// edit hook's `eslint_d`, a `script` wrapper re-parented to pid 1, found by working directory or mark.
 
 const PGREP_COMMAND = 'pgrep'
 const MATCH_FULL_COMMAND_LINE = '-f'
@@ -26,13 +29,24 @@ const CHILDREN_OF_FLAG = '-P'
 const PS_COMMAND = '/bin/ps'
 const PARENT_FORMAT = ['-o', 'ppid=', '-p']
 const TERMINATE_SIGNAL = 'SIGTERM'
+const CONTINUE_SIGNAL = 'SIGCONT'
 // `0` addresses the caller's own process group and `1` is init — neither is ever a lane child.
 const LOWEST_CHILD_PID = 2
 
-interface ReapProbes {
+// The lane a reap or a pause acts on: the child by its issue, the rest by its directory.
+interface LaneProcesses {
+	issue: string
+	directory: string
+}
+
+// What collecting a lane's process tree reads — shared with `lane:pause` (`lane-pause.ts`).
+interface TreeProbes {
 	matching: (pattern: string) => Array<number>
 	children_of: (pid: number) => Array<number>
 	parent_of: (pid: number) => number | undefined
+}
+
+interface ReapProbes extends TreeProbes {
 	terminate: (pid: number) => boolean
 }
 
@@ -64,9 +78,9 @@ function parent_of(pid: number): number | undefined {
 	return parse_pids(run_probe(PS_COMMAND, [...PARENT_FORMAT, String(pid)]))[0]
 }
 
-function terminate(pid: number): boolean {
+function send(pid: number, name: NodeJS.Signals): boolean {
 	try {
-		process.kill(pid, TERMINATE_SIGNAL)
+		process.kill(pid, name)
 
 		return true
 	} catch {
@@ -74,6 +88,16 @@ function terminate(pid: number): boolean {
 	}
 }
 
+// A stopped process (`lane:pause`) holds a SIGTERM it handles pending until it is continued, so the
+// terminate is followed by a SIGCONT; a running process ignores it.
+function terminate(pid: number): boolean {
+	if (!send(pid, TERMINATE_SIGNAL)) return false
+
+	send(pid, CONTINUE_SIGNAL)
+
+	return true
+}
+
 const SYSTEM_PROBES: ReapProbes = {
 	matching: (pattern) => parse_pids(run_probe(PGREP_COMMAND, [MATCH_FULL_COMMAND_LINE, pattern])),
 	children_of: (pid) => parse_pids(run_probe(PGREP_COMMAND, [CHILDREN_OF_FLAG, String(pid)])),
@@ -81,7 +105,7 @@ const SYSTEM_PROBES: ReapProbes = {
 	terminate,
 }
 
-function ancestry_of(pid: number, probes: ReapProbes): Set<number> {
+function ancestry_of(pid: number, probes: TreeProbes): Set<number> {
 	const ancestry = new Set<number>([pid])
 	let current = probes.parent_of(pid)
 
@@ -95,11 +119,11 @@ function ancestry_of(pid: number, probes: ReapProbes): Set<number> {
 
 // This process and every process above it. The Stop hook reads it to tell whether the session that
 // declared a carry record's `--owner "$PPID"` is the one it runs under.
-function own_ancestry(probes: ReapProbes = SYSTEM_PROBES): Set<number> {
+function own_ancestry(probes: TreeProbes = SYSTEM_PROBES): Set<number> {
 	return ancestry_of(process.pid, probes)
 }
 
-function tree_of(roots: ReadonlyArray<number>, probes: ReapProbes): Array<number> {
+function tree_of(roots: ReadonlyArray<number>, probes: TreeProbes): Array<number> {
 	const tree: Array<number> = []
 	const pending = [...roots]
 	let next = pending.shift()
@@ -116,35 +140,46 @@ function tree_of(roots: ReadonlyArray<number>, probes: ReapProbes): Array<number
 	return tree
 }
 
-function roots_of(issue: string, own: Set<number>, probes: ReapProbes): Array<number> {
+function roots_of(issue: string, own: Set<number>, probes: TreeProbes): Array<number> {
 	const pattern = lane_child_invocation.process_pattern(issue)
 
 	return probes.matching(pattern).filter((pid) => !own.has(pid))
 }
 
 /**
- * Terminate every process of the lane child for `issue` and everything under it, sparing the caller's
- * own ancestry. Returns the pids that were signalled — the empty list is the healthy case, a child
- * that had already ended by itself.
+ * Every process of the lane child for `issue` and everything under it, collected before anything is
+ * signalled, the caller's own ancestry left out.
  */
-function reap_child(issue: string, probes: ReapProbes = SYSTEM_PROBES): Array<number> {
+function lane_tree(issue: string, probes: TreeProbes = SYSTEM_PROBES): Array<number> {
 	const own = own_ancestry(probes)
-	const doomed = tree_of(roots_of(issue, own, probes), probes).filter((pid) => !own.has(pid))
 
-	return doomed.filter((pid) => probes.terminate(pid))
+	return tree_of(roots_of(issue, own, probes), probes).filter((pid) => !own.has(pid))
+}
+
+/**
+ * Terminate every process of the lane child for `lane.issue` and everything under it, sparing the
+ * caller's own ancestry. Returns the pids that were signalled — the empty list is the healthy case, a
+ * child that had already ended by itself.
+ */
+function reap_child(lane: LaneProcesses, probes: ReapProbes = SYSTEM_PROBES): Array<number> {
+	return lane_tree(lane.issue, probes).filter((pid) => probes.terminate(pid))
 }
 
 /** Whether a lane child for `issue` is running, by the same match `reap_child` would end. */
-function is_child_running(issue: string, probes: ReapProbes = SYSTEM_PROBES): boolean {
+function is_child_running(issue: string, probes: TreeProbes = SYSTEM_PROBES): boolean {
 	return roots_of(issue, own_ancestry(probes), probes).length > 0
 }
 
 const lane_reap = {
 	is_child_running,
+	lane_tree,
 	own_ancestry,
 	parse_pids,
+	PS_COMMAND,
 	reap_child,
+	run_probe,
+	SYSTEM_PROBES,
 }
 
-export type { ReapProbes }
+export type { LaneProcesses, ReapProbes, TreeProbes }
 export { lane_reap }

package/scripts/lane/lane-registry.ts

@@ -222,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)
 
@@ -279,6 +298,8 @@ const lane_registry = {
 	find_lane,
 	find_open_lane,
 	has_lanes_in_flight,
+	lane_location,
+	lane_root_directory,
 	list_lanes,
 	main_repository_root,
 	parse_block,

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

@@ -1,3 +1,4 @@
+import { git_stash } from '#scripts/git/stash/git-stash'
 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'
@@ -9,13 +10,14 @@ import { lane_dispatch, type DispatchOutcome } from './lane-dispatch'
 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.
@@ -35,6 +37,7 @@ const DISPATCHED_KIND = 'dispatched'
 const NO_LANE_KIND = 'no-lane'
 const NOT_RUNNING_KIND = 'not-running'
 const UNCLAIMED_KIND = 'unclaimed'
+const CONFLICTED_KIND = 'conflicted'
 
 type Unsaved = Extract<KeptWork, { kind: 'unsaved' }>
 
@@ -48,6 +51,7 @@ 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
 
 // A cut the stopped child carried would hand its successor the old session's hand-off at
@@ -85,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)
@@ -98,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 }
@@ -133,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

@@ -1,10 +1,12 @@
 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'
@@ -29,6 +31,8 @@ const stop_schema = z
 		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()
@@ -74,12 +78,22 @@ function review_prompt(lane: LaneInfo, round: ReviewRound): string {
 	return `${prompt_of(target.brief, target.findings, lane.issue)} This is ${tail}`
 }
 
-function reviewer_answer(result: AttachedLaunchResult): BrokerAnswer {
+// **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
-		: failure(`the reviewer exited with code ${String(result.exit_code)}`)
+	return result.exit_code === 0 ? SUCCESS : exited_answer(result.exit_code, log_path)
 }
 
 async function launch_review(lane: LaneInfo, round: ReviewRound): Promise<BrokerAnswer> {
@@ -103,7 +117,7 @@ async function launch_review(lane: LaneInfo, round: ReviewRound): Promise<Broker
 		console.error,
 	)
 
-	return reviewer_answer(result)
+	return reviewer_answer(result, target.log)
 }
 
 // An OpenAI lane's successor is its supervisor's to start, never a relaunch's.