@joshuafolkken/kit 1.872.0

package/scripts/lane/lane-reap.ts

@@ -0,0 +1,137 @@
+import { execFileSync } from 'node:child_process'
+import { lane_child_invocation } from './lane-child-invocation'
+
+// Ending a lane child that did not end itself (joshuafolkken/kit#2421).
+//
+// **A detached child is kept alive on purpose and was never ended by anything.** `detached_launch`
+// lets a child outlive its parent's session, and every reader of it — `run:liveness`, the 30-minute
+// silence window — only *reads* whether it stopped. So a child that merged and then hung on a wait
+// loop of its own lived on for a day, and the documented `pgrep -laf "fullrun #<N>$"` answered
+// `alive` for that issue number forever, which is a verification answering wrongly. The close and the
+// park are where the run has already decided the child is finished, so the reaping lives with them.
+//
+// **The whole process tree goes, collected before anything is signalled.** The hang is usually in a
+// shell the child spawned, not in the child itself, and a descendant signalled after its parent died
+// has already been re-parented out of reach — so the tree is read first, then terminated.
+//
+// **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.
+
+const PGREP_COMMAND = 'pgrep'
+const MATCH_FULL_COMMAND_LINE = '-f'
+const CHILDREN_OF_FLAG = '-P'
+// The same absolute `ps` `process-identity.ts` probes with, so the lookup does not depend on `PATH`.
+const PS_COMMAND = '/bin/ps'
+const PARENT_FORMAT = ['-o', 'ppid=', '-p']
+const TERMINATE_SIGNAL = 'SIGTERM'
+// A probe that hung would hang the close it runs inside; failing answers "no process", which leaves
+// the lane exactly as it was before this module existed.
+const PROBE_TIMEOUT_MS = 2000
+// `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 {
+	matching: (pattern: string) => Array<number>
+	children_of: (pid: number) => Array<number>
+	parent_of: (pid: number) => number | undefined
+	terminate: (pid: number) => boolean
+}
+
+function parse_pids(printed: string): Array<number> {
+	return printed
+		.split('\n')
+		.map((line) => Number(line.trim()))
+		.filter((pid) => Number.isSafeInteger(pid) && pid >= LOWEST_CHILD_PID)
+}
+
+// `pgrep` exits 1 when nothing matches, which `execFileSync` throws — the empty list either way.
+function run_probe(command: string, args: ReadonlyArray<string>): string {
+	try {
+		return execFileSync(command, [...args], {
+			encoding: 'utf8',
+			timeout: PROBE_TIMEOUT_MS,
+			stdio: ['ignore', 'pipe', 'ignore'],
+		})
+	} catch {
+		return ''
+	}
+}
+
+function parent_of(pid: number): number | undefined {
+	return parse_pids(run_probe(PS_COMMAND, [...PARENT_FORMAT, String(pid)]))[0]
+}
+
+function terminate(pid: number): boolean {
+	try {
+		process.kill(pid, TERMINATE_SIGNAL)
+
+		return true
+	} catch {
+		return false
+	}
+}
+
+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)])),
+	parent_of,
+	terminate,
+}
+
+function ancestry_of(pid: number, probes: ReapProbes): Set<number> {
+	const ancestry = new Set<number>([pid])
+	let current = probes.parent_of(pid)
+
+	while (current !== undefined && !ancestry.has(current)) {
+		ancestry.add(current)
+		current = probes.parent_of(current)
+	}
+
+	return ancestry
+}
+
+// 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 (joshuafolkken/kit#2472).
+function own_ancestry(probes: ReapProbes = SYSTEM_PROBES): Set<number> {
+	return ancestry_of(process.pid, probes)
+}
+
+function tree_of(roots: ReadonlyArray<number>, probes: ReapProbes): Array<number> {
+	const tree: Array<number> = []
+	const pending = [...roots]
+	let next = pending.shift()
+
+	while (next !== undefined) {
+		if (!tree.includes(next)) {
+			tree.push(next)
+			pending.push(...probes.children_of(next))
+		}
+
+		next = pending.shift()
+	}
+
+	return tree
+}
+
+/**
+ * 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.
+ */
+function reap_child(issue: string, probes: ReapProbes = SYSTEM_PROBES): Array<number> {
+	const own = own_ancestry(probes)
+	const pattern = lane_child_invocation.process_pattern(issue)
+	const roots = probes.matching(pattern).filter((pid) => !own.has(pid))
+	const doomed = tree_of(roots, probes).filter((pid) => !own.has(pid))
+
+	return doomed.filter((pid) => probes.terminate(pid))
+}
+
+const lane_reap = {
+	own_ancestry,
+	parse_pids,
+	reap_child,
+}
+
+export type { ReapProbes }
+export { lane_reap }

package/scripts/lane/lane-registry.ts

@@ -0,0 +1,261 @@
+import { existsSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+import { ENV_FILE_NAME } from '#ports'
+import type { AgentProfile } from '#scripts/agent/agent-role-profile'
+import { repo_discovery } from '#scripts/discovery/repo-discovery'
+import { git_command } from '#scripts/git/git-command'
+import { git_worktree } from '#scripts/git/git-worktree'
+import { lane_environment } from './lane-environment'
+import { lane_paths } from './lane-paths'
+
+// The open lanes, read from git and from each lane's own `.env` (joshuafolkken/kit#1490).
+//
+// **There is no ledger file, and that is the design rather than an omission.** A lane's seat has to
+// live in its `.env` anyway — that file is what `josh port` and `playwright.config.ts` read inside
+// the work tree — so keeping a second copy of it anywhere else buys nothing and can disagree with
+// the first. Reading the seats back out of the live lanes means `git worktree remove` erases the
+// record of a seat along with the tree that held it: there is nothing to keep in step and nothing
+// 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.
+
+interface LaneInfo {
+	issue: string
+	branch: string
+	directory: string
+	// The lane's seat (`JOSH_LANE_SEAT`, 1..9), and the dev/preview ports it resolves to through
+	// `ports/index.js` — all `undefined` when the lane's `.env` cannot be read. The seat is what a new
+	// lane's allocation has to avoid; the ports are what the report shows (joshuafolkken/kit#1494).
+	seat: number | undefined
+	development_port: number | undefined
+	preview_port: number | undefined
+	// Where the delegated unit running this lane's child writes (joshuafolkken/kit#1713), or
+	// `undefined` where the lane records none. It is the one thing about a lane that a session which
+	// did not open it cannot derive: the harness names a unit's file after the dispatching session
+	// and the unit's own id, neither of which is written anywhere else on disk. Recorded here, a
+	// fresh session can poll a running child with `pnpm josh run:liveness <N> --output <path>`
+	// instead of waiting for the pool to drain before it can be cut.
+	output: string | undefined
+	profile?: AgentProfile | undefined
+	is_stranded: boolean
+}
+
+const WORKTREE_PREFIX = 'worktree '
+const BRANCH_PREFIX = 'branch refs/heads/'
+const BLOCK_SEPARATOR = '\n\n'
+// The same shape `lane:open` accepts. Nothing reserves the `-lane` suffix, so a hand-made
+// `spike-lane` branch with a work tree would otherwise be read as a lane — and `lane:close --all`
+// would delete its directory and its branch on an issue number that never existed.
+const ISSUE_PATTERN = /^[1-9]\d*$/u
+
+function line_value(lines: ReadonlyArray<string>, prefix: string): string | undefined {
+	return lines.find((line) => line.startsWith(prefix))?.slice(prefix.length)
+}
+
+interface LaneSeat {
+	seat: number
+	development_port: number
+	preview_port: number
+}
+
+/**
+ * The seat and ports a lane holds, or `undefined` when its `.env` records no seat.
+ *
+ * **Unreadable is reported, never treated as free.** A seat read as free is handed to the next lane
+ * while the ports it actually holds are still bound, and the collision then surfaces as an E2E
+ * failure in a different work tree — the kind of silent failure `playwright.config.ts` refuses to
+ * add by dying on a busy port instead of retrying on another.
+ *
+ * **A file with no `JOSH_LANE_SEAT` line is not seat 0.** Seat 0 is the main work tree's own, so a
+ * lane whose seat line was lost would be booked as sharing it while it in fact still runs on
+ * whatever ports it was started with, and `lane:open` would allocate straight over them.
+ */
+function seat_from_content(content: string): LaneSeat | undefined {
+	const seat = lane_environment.read_lane_seat(content)
+	if (seat === undefined) return undefined
+
+	const port_pair = lane_environment.read_lane_ports(content)
+
+	return { seat, development_port: port_pair.development, preview_port: port_pair.preview }
+}
+
+interface SeatPorts {
+	seat: number | undefined
+	development_port: number | undefined
+	preview_port: number | undefined
+}
+
+const EMPTY_SEAT: SeatPorts = {
+	seat: undefined,
+	development_port: undefined,
+	preview_port: undefined,
+}
+
+// A stranded or unreadable lane holds no seat and binds no ports, so all three fields read undefined.
+function held_seat(content: string | undefined): SeatPorts {
+	if (content === undefined) return EMPTY_SEAT
+
+	return seat_from_content(content) ?? EMPTY_SEAT
+}
+
+/**
+ * The lane's own `.env`, or `undefined` when it cannot be read.
+ *
+ * One read serves both the seat and the recorded output path (joshuafolkken/kit#1713). Reading the
+ * file twice would let the two disagree about whether it could be read at all, and `unreadable` is
+ * a state the report shows rather than a state anything falls back from.
+ */
+function read_environment(directory: string): string | undefined {
+	try {
+		return readFileSync(path.join(directory, ENV_FILE_NAME), 'utf8')
+	} catch {
+		return undefined
+	}
+}
+
+// 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.
+function branch_issue(branch: string | undefined): string | undefined {
+	if (!branch?.endsWith(lane_paths.LANE_BRANCH_SUFFIX)) return undefined
+
+	const issue = branch.slice(0, -lane_paths.LANE_BRANCH_SUFFIX.length)
+
+	return ISSUE_PATTERN.test(issue) ? issue : undefined
+}
+
+// **Stranded means the work tree is gone from disk, and nothing else.** git also marks a
+// registration prunable when its `.git` pointer is damaged while the directory — and whatever server
+// is running in it — is still there; read as stranded, that lane's seat would be handed to the next
+// one while its ports are still bound.
+function is_gone(directory: string): boolean {
+	return !existsSync(directory)
+}
+
+function build_lane(
+	issue: string,
+	branch: string,
+	directory: string,
+	is_stranded: boolean,
+): LaneInfo {
+	// A stranded lane binds no ports and runs nothing, so its seat is free and there is nothing to
+	// read — its work tree is gone from disk along with the `.env` that held both records.
+	const content = is_stranded ? undefined : read_environment(directory)
+	const held = held_seat(content)
+	const output = content === undefined ? undefined : lane_environment.read_lane_output(content)
+	const profile = content === undefined ? undefined : lane_environment.read_lane_profile(content)
+
+	return {
+		issue,
+		branch,
+		directory,
+		seat: held.seat,
+		development_port: held.development_port,
+		preview_port: held.preview_port,
+		output,
+		profile,
+		is_stranded,
+	}
+}
+
+// **A lane is its branch *and* its place, and the place is what makes the identification safe**
+// (joshuafolkken/kit#1497). The branch alone is not a namespace anyone stays out of: `pnpm josh git`
+// builds an issue branch as `<N>-<slug of the title>`, so an issue titled "Lane" produces `<N>-lane`
+// — byte for byte the name `lane_paths.lane_branch` builds. Read as a lane, that work tree is
+// whichever checkout the person was working in, and `lane:close --all` would delete it, because
+// `lane-close.ts` → `remove_directory` runs `rmSync` on whatever directory the registry reported.
+// Requiring the directory to be exactly `<lane root>/<N>` costs a real lane nothing — `lane:open`
+// puts it there and nowhere else — and takes the whole class of collision out. The cost is that a
+// lane root reached through a symlink stops reading as a lane; that fails safe, where the branch
+// check alone failed destructively.
+function is_lane_directory(root: string, issue: string, directory: string): boolean {
+	return directory === lane_paths.lane_directory(root, issue)
+}
+
+function parse_block(block: string, root: string): LaneInfo | undefined {
+	const lines = block.split('\n')
+	const directory = line_value(lines, WORKTREE_PREFIX)
+	const branch = line_value(lines, BRANCH_PREFIX)
+	const issue = branch_issue(branch)
+
+	if (directory === undefined || branch === undefined || issue === undefined) return undefined
+
+	if (!is_lane_directory(root, issue, directory)) return undefined
+
+	return build_lane(issue, branch, directory, is_gone(directory))
+}
+
+function is_lane(lane: LaneInfo | undefined): lane is LaneInfo {
+	return lane !== undefined
+}
+
+async function worktree_blocks(): Promise<Array<string>> {
+	const listing = await git_worktree.worktree_list()
+
+	return listing.split(BLOCK_SEPARATOR)
+}
+
+/**
+ * The main work tree's root, whichever work tree this was run in.
+ *
+ * **Every lane path is derived from here, and `git rev-parse --show-toplevel` is not it**
+ * (joshuafolkken/kit#1497). That answers the *current* work tree, which inside a lane is the lane
+ * itself — so `lane:list` run there would look for lanes under `<lane>/.<lane>-lanes` and report that
+ * none are open while six are running. The step from the current work tree to the main one is exactly
+ * what `repo_discovery.main_worktree` resolves from the filesystem (joshuafolkken/kit#2233), so this
+ * is a thin async layer over it: `repository_root()` names the current work tree, and the shared
+ * resolver walks its `.git`/`commondir` up to the main checkout. Keeping that walk in one place lets
+ * the synchronous discovery callers — which cannot await this — share the same answer. For an ordinary
+ * checkout the resolver is a no-op, so `main_repository_root` is unchanged outside a lane.
+ */
+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())
+	const blocks = await worktree_blocks()
+	const lanes = blocks.map((block) => parse_block(block, root)).filter(is_lane)
+
+	return lanes.toSorted((left, right) => Number(left.issue) - Number(right.issue))
+}
+
+/** 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)
+}
+
+/** The live lanes whose seat could not be read, which is what stops an allocation. */
+function unreadable_lanes(lanes: ReadonlyArray<LaneInfo>): Array<LaneInfo> {
+	return lanes.filter((lane) => !lane.is_stranded && lane.seat === undefined)
+}
+
+function find_lane(lanes: ReadonlyArray<LaneInfo>, issue: string): LaneInfo | undefined {
+	return lanes.find((lane) => lane.issue === issue)
+}
+
+/**
+ * The open lane for one issue, read from the listing every other lane reading goes through.
+ *
+ * **The listing and the find are one call because every caller needs both** (joshuafolkken/kit#1749).
+ * Each one that wrote the pair itself is a place the listing could be read differently — from a cache,
+ * from a stale array — and the whole point of reading it live is that the answer is the same in every
+ * session, including one that never opened the lane.
+ */
+async function find_open_lane(issue: string): Promise<LaneInfo | undefined> {
+	return find_lane(await list_lanes(), issue)
+}
+
+const lane_registry = {
+	find_lane,
+	find_open_lane,
+	list_lanes,
+	main_repository_root,
+	parse_block,
+	read_environment,
+	unreadable_lanes,
+	used_seats,
+}
+
+export type { LaneInfo }
+export { lane_registry }

package/scripts/lane/lane-relaunch.ts

@@ -0,0 +1,68 @@
+import { agent_argv } from '#scripts/agent/agent-argv'
+import { detached_launch, type LaunchResult } from '#scripts/run/detached-launch'
+import { run_ship_detach } from '#scripts/run/run-ship-detach'
+import { lane_child_invocation } from './lane-child-invocation'
+import { lane_child_marker } from './lane-child-marker'
+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
+// log and carrying the dispatch mark afresh. **It was `run:cut`'s alone until a second caller needed it**
+// (joshuafolkken/kit#2428): 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
+// copy that drifts is the one that forgets the mark and is read as a person by every guard.
+//
+// The prompt is the caller's: each composes it from `lane-child-invocation.ts`, and every one of them
+// ends with the bare `fullrun #<N>` so the parent's liveness poll keeps matching the relaunched process.
+
+const { SUPERVISED_KEY } = run_ship_detach
+const OPENAI_PROVIDER = 'openai'
+
+type RelaunchResult = LaunchResult | { kind: 'rejected'; note: string }
+
+function relaunch(
+	lane: LaneInfo,
+	invocation: string,
+	phase: string,
+	on_note: (note: string) => void,
+): RelaunchResult {
+	const built = agent_argv.resume_argv(invocation, lane.profile, phase, lane.directory)
+
+	if (built.kind === 'rejected') return built
+
+	return detached_launch.launch(
+		{
+			argv: built.argv,
+			cwd: lane.directory,
+			log_path: lane_dispatch_log.default_log_path(lane),
+			profile: built.profile,
+			// The relaunch keeps the mark, so the resumed child is still a dispatched child to every rule
+			// that reads it (joshuafolkken/kit#1904); the inherited environment cannot be relied on here,
+			// since the parent-session strip runs on the way in. **The ship supervisor's mark is dropped**
+			// (joshuafolkken/kit#2428): a detached supervisor is what relaunches after a stopped stage, and an
+			// agent that inherited its mark would read its own in-turn `josh ship` failure as a supervisor's —
+			// relaunching a second child into the lane beside itself.
+			env: { ...lane_child_marker.env_for(lane.issue), [SUPERVISED_KEY]: undefined },
+		},
+		on_note,
+	)
+}
+
+// An OpenAI lane's process is started by its supervisor, never by a relaunch — both `run:cut` and the
+// `run:merge` cut fallback ask this one predicate (joshuafolkken/kit#2484).
+function is_openai_lane(lane: LaneInfo): boolean {
+	return lane.profile?.provider === OPENAI_PROVIDER
+}
+
+// The relaunch after a cut: the resume-specific prompt, not the record's bare `fullrun #<N>`
+// (joshuafolkken/kit#2022), so the successor goes straight to `run:cut --resume` without reading the
+// workflow-commands entry documents. Shared by `run:cut` and the `run:merge` fallback (joshuafolkken/kit#2484).
+function resume(lane: LaneInfo, phase: string, on_note: (note: string) => void): RelaunchResult {
+	return relaunch(lane, lane_child_invocation.resume_invocation(lane.issue), phase, on_note)
+}
+
+const lane_relaunch = { is_openai_lane, relaunch, resume }
+
+export type { RelaunchResult }
+export { lane_relaunch }

package/scripts/lane/lane-report.ts

@@ -0,0 +1,95 @@
+import { agent_role_profile } from '#scripts/agent/agent-role-profile'
+import { run_liveness } from '#scripts/run/run-liveness'
+import type { LaneInfo } from './lane-registry'
+
+// What a person reads when they ask what is open (joshuafolkken/kit#1490, joshuafolkken/kit#1494).
+//
+// The dev and preview ports are the ones the registry already resolved through `ports/index.js`
+// when it read each lane's `.env`, so the numbers printed here are the same ones `josh port` and
+// `playwright.config.ts` resolve inside the lane — nothing recomputes them, so there is no second
+// formula for the two to disagree over.
+
+const NO_LANES = 'No lanes are open.'
+const OPEN_STATE = 'open'
+// A registration whose work tree is gone: what an interruption leaves, and what `lane:prune` clears.
+const STRANDED_STATE = 'stranded'
+// A live lane whose `.env` cannot be read. It is shown rather than hidden, because it is what stops
+// the next `lane:open` — a state nobody could see would look like an unexplained refusal.
+const UNREADABLE_STATE = 'unreadable'
+const UNKNOWN_VALUE = '-'
+const COLUMN_SEPARATOR = '  '
+
+function lane_state(lane: LaneInfo): string {
+	if (lane.is_stranded) return STRANDED_STATE
+
+	return lane.seat === undefined ? UNREADABLE_STATE : OPEN_STATE
+}
+
+function value_or_unknown(value: number | undefined): string {
+	return value === undefined ? UNKNOWN_VALUE : String(value)
+}
+
+// The recorded output path goes last and is labelled, so it is told apart from the directory beside
+// it (joshuafolkken/kit#1713). A lane that records none prints `output -` rather than nothing at
+// all: a session that did not open the lane has to be able to see that the record is missing, not
+// read a shorter row as one field it failed to notice.
+function output_column(output: string | undefined): string {
+	return `output ${output ?? UNKNOWN_VALUE}`
+}
+
+function profile_column(lane: LaneInfo): string {
+	return `profile ${lane.profile === undefined ? UNKNOWN_VALUE : agent_role_profile.describe(lane.profile)}`
+}
+
+function event_column(lane: LaneInfo): string {
+	if (lane.output === undefined) return 'agent -'
+	const state = run_liveness.describe_agent_state(lane.output)
+
+	return state ?? 'agent -'
+}
+
+function describe_lane(lane: LaneInfo): string {
+	return [
+		`#${lane.issue}`,
+		`seat ${value_or_unknown(lane.seat)}`,
+		`dev ${value_or_unknown(lane.development_port)}`,
+		`preview ${value_or_unknown(lane.preview_port)}`,
+		lane.branch,
+		lane_state(lane),
+		lane.directory,
+		output_column(lane.output),
+		profile_column(lane),
+		event_column(lane),
+	].join(COLUMN_SEPARATOR)
+}
+
+function describe_lanes(lanes: ReadonlyArray<LaneInfo>): string {
+	if (lanes.length === 0) return NO_LANES
+
+	return lanes.map((lane) => describe_lane(lane)).join('\n')
+}
+
+function describe_ports(lane: LaneInfo): string {
+	if (lane.seat === undefined) return 'no lane seat could be read'
+
+	return `seat ${String(lane.seat)}, dev ${value_or_unknown(lane.development_port)}, preview ${value_or_unknown(lane.preview_port)}`
+}
+
+// The one-line confirmation a person reads on standard error while standard output carries the
+// directory alone, so `dir=$(pnpm josh lane:open 1490)` stays usable.
+function describe_opened(lane: LaneInfo): string {
+	return `Opened a lane for #${lane.issue} on ${lane.branch}: ${describe_ports(lane)}.`
+}
+
+const lane_report = {
+	NO_LANES,
+	OPEN_STATE,
+	STRANDED_STATE,
+	UNREADABLE_STATE,
+	describe_lane,
+	describe_lanes,
+	describe_opened,
+	lane_state,
+}
+
+export { lane_report }

package/scripts/lane/lane-resume.ts

@@ -0,0 +1,61 @@
+import type { AgentProvider } from '#scripts/agent/agent-role-profile'
+import { api_outage } from '#scripts/agent/api-outage'
+import type { ClaudeResultEvent } from '#scripts/agent/claude-result-event'
+import { lane_child_invocation } from './lane-child-invocation'
+
+// How a lane re-dispatch chooses between resuming the disconnected child's session and starting fresh
+// (joshuafolkken/kit#2317). The premise the whole issue rests on: a child that could not reach the API
+// left a `session_id` in its exit record, and re-dispatching it as a bare `fullrun #<N>` threw that
+// context away — a resumed child keeps it and loses only the last round-trip.
+//
+// **The decision is pure and reads three inputs**: the child's exit record, and the provider the lane
+// runs under. It resumes only when all three hold — the record is an API outage (a child that stalled
+// on its own has nothing to recover), it carries a `session_id`, and the provider is Anthropic (the
+// `--resume` mechanism is Claude Code's; an OpenAI lane has no session id here and falls back to fresh).
+// Every other case is `fresh`, which is the exact behavior a first dispatch and a non-outage ending had
+// before this existed, so the fallback is never a regression.
+
+const ANTHROPIC: AgentProvider = 'anthropic'
+
+// A resume carries the stored session and the resume-specific prompt; a fresh start carries the
+// ordinary `fullrun #<N>`. The caller reads `kind` to report which path it took and to pick the argv
+// builder — the resume builder needs the `session_id` the fresh one does not.
+type ResumePlan =
+	{ kind: 'resume'; session_id: string; invocation: string } | { kind: 'fresh'; invocation: string }
+
+function fresh_plan(issue: string): ResumePlan {
+	return { kind: 'fresh', invocation: lane_child_invocation.child_invocation(issue) }
+}
+
+// The session id to resume from, or `undefined` when this ending is not resumable — the three
+// conditions named in the header, read in one place so the caller's fallback is a single branch. An
+// Anthropic outage child that left a session id is the only case that yields one.
+function resumable_session(
+	record: ClaudeResultEvent | undefined,
+	provider: AgentProvider,
+): string | undefined {
+	if (provider !== ANTHROPIC || record === undefined) return undefined
+
+	return api_outage.is_outage(record) ? record.session_id : undefined
+}
+
+function plan(
+	issue: string,
+	record: ClaudeResultEvent | undefined,
+	provider: AgentProvider,
+): ResumePlan {
+	const session_id = resumable_session(record, provider)
+
+	if (session_id === undefined) return fresh_plan(issue)
+
+	return {
+		kind: 'resume',
+		session_id,
+		invocation: lane_child_invocation.outage_resume_invocation(issue),
+	}
+}
+
+const lane_resume = { plan }
+
+export type { ResumePlan }
+export { lane_resume }

package/scripts/lane/lane-seed.ts

@@ -0,0 +1,44 @@
+// Which seat a lane gets (joshuafolkken/kit#1490, joshuafolkken/kit#1494).
+
+// **The main work tree is seat 0, and nothing here can move it.** Lanes take seats 1..9, so a
+// project that has never opened one stays on exactly the ports `ports/index.js` already gives it —
+// `seed × 10` for its seed, the bases themselves for an unset seed, which is what CI runs on.
+const FIRST_LANE_SEAT = 1
+// **Nine seats, because the seat is the units digit of the offset `seed × 10 + lane`.** The seat no
+// longer carries the whole port band — the seed does, multiplied by ten — so a lane holds a single
+// seat number rather than an absolute seed, and there is no ceiling to check and no "multiple of
+// ten" convention for anyone to break (joshuafolkken/kit#1494 removed the band mechanism).
+const LAST_LANE_SEAT = 9
+
+/**
+ * The free seats, lowest first — the ones no live lane holds.
+ *
+ * **Read from the lanes themselves — never from a counter.** A number derived from how many lanes
+ * have ever been opened hands a closed-and-reopened lane the seat a running lane is still using; the
+ * seats here come from the `JOSH_LANE_SEAT` of each open work tree, so closing one frees its seat and
+ * nothing else has to be told. **An empty result means the caller fails** — the range is never
+ * wrapped, because wrapping is that same collision under a friendlier name.
+ *
+ * The whole ascending list is returned rather than only the lowest, because the caller claims each
+ * seat atomically and steps to the next when a concurrent `lane:open` claimed it first
+ * (joshuafolkken/kit#1494): reading a free set and picking from it are two moments, and the gap
+ * between them is where two opens once chose the same seat.
+ */
+function free_seats(used: ReadonlyArray<number>): Array<number> {
+	const taken = new Set(used)
+	const free: Array<number> = []
+
+	for (let seat = FIRST_LANE_SEAT; seat <= LAST_LANE_SEAT; seat += 1) {
+		if (!taken.has(seat)) free.push(seat)
+	}
+
+	return free
+}
+
+const lane_seed_policy = {
+	FIRST_LANE_SEAT,
+	LAST_LANE_SEAT,
+	free_seats,
+}
+
+export { lane_seed_policy }