@joshuafolkken/kit 1.1514.0 → 1.2114.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

@@ -1,4 +1,4 @@
-import { existsSync, statSync } from 'node:fs'
+import { chmodSync, existsSync, statSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
 import { ENV_FILE_NAME } from '#ports'
 import type { AgentProfile } from '#scripts/agent/agent-role-profile'
@@ -20,6 +20,8 @@ import { lane_paths } from './lane-paths'
 // that can go stale. A counter, or a ledger beside the trees, would let a lane that was closed and
 // reopened take a seat a running lane is still using.
 
+const OWNER_ONLY_MODE = 0o600
+
 interface LaneInfo {
 	issue: string
 	branch: string
@@ -109,6 +111,15 @@ function read_environment(directory: string): string | undefined {
 	return file_reader.read_if_readable(path.join(directory, ENV_FILE_NAME))
 }
 
+// The lane's `.env` carries the root's secrets (the Telegram token), so it is readable by its owner
+// alone. `mode` applies only to a file the write creates, so an existing one is narrowed after.
+function write_environment(directory: string, content: string): void {
+	const file = path.join(directory, ENV_FILE_NAME)
+
+	writeFileSync(file, content, { mode: OWNER_ONLY_MODE })
+	chmodSync(file, OWNER_ONLY_MODE)
+}
+
 function dispatched_at(directory: string): number | undefined {
 	return statSync(path.join(directory, ENV_FILE_NAME), { throwIfNoEntry: false })?.mtimeMs
 }
@@ -222,9 +233,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 +309,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,
@@ -286,6 +318,8 @@ const lane_registry = {
 	registered_directories,
 	unreadable_lanes,
 	used_seats,
+	write_environment,
+	OWNER_ONLY_MODE,
 }
 
 export type { LaneInfo }

package/scripts/lane/lane-relaunch.ts

@@ -7,7 +7,7 @@ import { lane_dispatch_log } from './lane-dispatch-log'
 import type { LaneInfo } from './lane-registry'
 
 // Relaunching a lane child session into its own lane — a fresh agent process started detached, under
-// the lane's stored profile at the effort of the phase it resumes into, logging to the lane's dispatch
+// the lane's stored profile at the effort (and any model override) of the phase it resumes into, logging to the lane's dispatch
 // log and carrying the dispatch mark afresh. **It was `run:cut`'s alone until a second caller needed it**:
 // the detached `josh ship` supervisor hands a stopped stage back to an agent
 // the same way the pre-gate cut hands the gate to one, so the launch is shared rather than copied — the

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-one-stats.ts

@@ -0,0 +1,51 @@
+import { lane_ledger, type LedgerEntry, type RoundOneEntry } from './lane-ledger'
+import { lane_stats, type StatsWindow } from './lane-stats'
+
+// How a `josh ship`'s round 1 ended: the ledger's `round-one` entries of one period, one row per
+// verdict, with each reviewed verdict's share of the rounds the ship ran. The `clean` share is the rate
+// a ship-time round 1 passed with no fix — the number the "CI beside the review" break-even of
+// `docs/maintainers/lane-limit-measurement.md` is read against (joshuafolkken/kit#4620). A `reused`
+// round never ran, so it has a count and no share.
+
+const COLUMNS = ['round 1', 'rounds', 'share'] as const
+const VERDICTS = ['clean', 'fixed', 'blocking'] as const
+const { ROUND_ONE_REUSED: REUSED } = lane_ledger
+const NO_SHARE = '-'
+const PERCENT = 100
+
+function is_round_one(entry: LedgerEntry): entry is RoundOneEntry {
+	return entry.kind === lane_ledger.KIND.ROUND_ONE
+}
+
+function count_of(rounds: ReadonlyArray<RoundOneEntry>, verdict: string): number {
+	return rounds.filter((round) => round.verdict === verdict).length
+}
+
+function share_of(count: number, ran: number): string {
+	if (ran === 0) return NO_SHARE
+
+	return `${String(Math.round((count * PERCENT) / ran))}%`
+}
+
+// The period's table: `entries` is the whole ledger, filtered here to `window`.
+function table(entries: ReadonlyArray<LedgerEntry>, window: StatsWindow): string {
+	const rounds = lane_stats.in_window(entries, window).filter(is_round_one)
+	const counts = VERDICTS.map((verdict) => count_of(rounds, verdict))
+	const ran = counts.reduce((sum, count) => sum + count, 0)
+	const rows = VERDICTS.map((verdict, index) => {
+		const count = counts[index] ?? 0
+
+		return lane_stats.to_row([verdict, String(count), share_of(count, ran)])
+	})
+
+	return [
+		lane_stats.to_row(COLUMNS),
+		lane_stats.to_row(COLUMNS.map(() => '---')),
+		...rows,
+		lane_stats.to_row([REUSED, String(count_of(rounds, REUSED)), NO_SHARE]),
+	].join('\n')
+}
+
+const lane_round_one_stats = { table }
+
+export { lane_round_one_stats }