@joshuafolkken/kit 1.1387.0 → 1.1435.0

package/scripts/josh/josh-commands-project.ts

@@ -29,6 +29,24 @@ const PROJECT_COMMANDS: Record<string, CommandEntry> = {
 		reference: ['<dir>', 'automation', ['files', 'git']],
 		is_kit_only: true,
 	},
+	'fresh:run': {
+		script: 'scripts/fresh-machine/fresh-machine-cli.ts',
+		description:
+			'Run an install scenario in a Docker container of a machine with nothing installed, and keep the log',
+		category: 'Project',
+		reference: [
+			'<pattern> | --spec <file.json> [--package-version <version>] [--log-dir <dir>] [--rebuild] | --list',
+			'maintainer',
+			['files', 'network', 'processes'],
+		],
+	},
+	'auth:setup': {
+		script: 'scripts/auth/auth-setup-cli.ts',
+		description:
+			'Save the long-lived Claude Code token `claude setup-token` prints in the macOS keychain, for josh fresh:run',
+		category: 'Project',
+		reference: ['[--check]', 'maintainer', ['network', 'processes']],
+	},
 	init: {
 		script: 'scripts/init/init.ts',
 		description: 'Initialize config in a new project',
@@ -45,6 +63,12 @@ const PROJECT_COMMANDS: Record<string, CommandEntry> = {
 		category: 'Project',
 		reference: ['', 'developer', ['files']],
 	},
+	uninstall: {
+		script: 'scripts/uninstall/uninstall.ts',
+		description: 'Remove what kit added to a project and list what is left to review by hand',
+		category: 'Project',
+		reference: [`${PROFILE_ARGUMENTS} [--yes]`, 'developer', ['files', 'processes']],
+	},
 	'registry:migrate': {
 		script: 'scripts/registry-migration/migrate.ts',
 		description: 'Migrate a project from GitHub Packages to public npm',

package/scripts/josh/josh-verdict.ts

@@ -35,7 +35,7 @@ import { status_icons } from '#scripts/lib/status-icons'
 // gate's plan line is what says "the gate starts here", and it is single-sourced for the reason the
 // verdict is: the printer builds it and the detector matches it from one place.
 
-const { FAIL_ICON, PASS_ICON } = status_icons
+const { FAIL_ICON, PASS_ICON, WARN_ICON } = status_icons
 const GATE_SUBJECT = 'verification gate'
 
 // The prefixes are what the detector matches **and** what the printer builds its line from, so a
@@ -43,16 +43,41 @@ const GATE_SUBJECT = 'verification gate'
 // this module exists to prevent.
 const GATE_PASSED_PREFIX = `${PASS_ICON} ${GATE_SUBJECT} passed`
 const GATE_FAILED_PREFIX = `${FAIL_ICON} ${GATE_SUBJECT} failed`
+// **A gate that ran no check has not passed, and it has not failed either.** Every check of a `basic`
+// project with nothing to check exits 0 with a skip notice, which is a legitimate state — the exit code
+// stays 0, or such a project could never commit — but a line reading `passed` made it indistinguishable
+// from a gate that ran every check. It opens with neither icon and neither word, so no reader of the
+// other two prefixes can take it for one of them.
+const GATE_UNVERIFIED_PREFIX = `${WARN_ICON} ${GATE_SUBJECT} not verified`
 
-type JoshVerdict = 'passed' | 'failed'
+type JoshVerdict = 'passed' | 'failed' | 'unverified'
 
 // Typed rather than left to inference: the namespace object widens a bare literal to `string`, and a
 // caller comparing `read_verdict(line)` against it would then be comparing two unrelated types.
 const PASSED_VERDICT: JoshVerdict = 'passed'
 const FAILED_VERDICT: JoshVerdict = 'failed'
+const UNVERIFIED_VERDICT: JoshVerdict = 'unverified'
 
-function format_gate_passed(step_count: string, total: string): string {
-	return `${GATE_PASSED_PREFIX} (${step_count} checks) in ${total}.`
+// How many of a gate's checks ran, and how many passed without running.
+interface GateCounts {
+	ran: number
+	skipped: number
+}
+
+// The split is printed only when there is one. A gate that skipped nothing — kit's own, and an ordinary
+// consumer's — keeps the line it always printed.
+function format_counts(counts: GateCounts): string {
+	if (counts.skipped === 0) return `${String(counts.ran)} checks`
+
+	return `${String(counts.ran)} ran, ${String(counts.skipped)} skipped`
+}
+
+function format_gate_passed(counts: GateCounts, total: string): string {
+	return `${GATE_PASSED_PREFIX} (${format_counts(counts)}) in ${total}.`
+}
+
+function format_gate_unverified(skipped: number, total: string): string {
+	return `${GATE_UNVERIFIED_PREFIX} (0 ran, ${String(skipped)} skipped) in ${total}.`
 }
 
 function format_gate_failed(failed_labels: string, total: string): string {
@@ -91,14 +116,18 @@ function read_verdict(line: string): JoshVerdict | undefined {
 
 	if (trimmed.startsWith(GATE_PASSED_PREFIX)) return PASSED_VERDICT
 
+	if (trimmed.startsWith(GATE_UNVERIFIED_PREFIX)) return UNVERIFIED_VERDICT
+
 	return undefined
 }
 
 const josh_verdict = {
 	PASSED_VERDICT,
 	FAILED_VERDICT,
+	UNVERIFIED_VERDICT,
 	format_gate_passed,
 	format_gate_failed,
+	format_gate_unverified,
 	GATE_OPENING_MARK,
 	GATE_OPENING_PREFIX,
 	is_gate_opening,

package/scripts/lane/claude-lane-broker.ts

@@ -0,0 +1,142 @@
+import { error_text } from '#scripts/lib/error-message'
+import { lane_registry, type LaneInfo } from './lane-registry'
+import { lane_relaunch } from './lane-relaunch'
+import { lane_session_broker } from './lane-session-broker'
+
+// The lane broker for every open Claude lane, run inside the `run:wake` supervisor for as long as the
+// supervisor runs, so nobody has to start or stop it.
+//
+// **It lives in the supervisor because the supervisor is what holds the token.** `josh backlogrun`
+// starts it from the terminal (joshuafolkken/kit#3804), so every session it starts can sign in with a
+// token-only credential. A lane child's detached `josh ship` cannot: it descends from the child's Bash
+// tool, which Claude Code starts without the token (joshuafolkken/kit#3817). Its reviewer and its relaunch
+// are asked of this broker instead (`lane-session-broker.ts`).
+//
+// **Not inside one `backlog:drive`**: the supervisor runs a drive per pass, and a lane's ship reaches its
+// review whenever it does — while the drive has handed back to a session too, when no drive runs.
+//
+// An OpenAI lane is left to its own supervisor, which serves the same broker for that lane's lifetime;
+// two servers for one lane would overwrite each other's response.
+
+const SCAN_INTERVAL_MS = 5000
+
+type ListLanes = () => Promise<ReadonlyArray<LaneInfo>>
+
+interface Served {
+	stop: () => void
+	done: Promise<void>
+}
+
+function is_served(lane: LaneInfo): boolean {
+	return !lane.is_stranded && !lane_relaunch.is_openai_lane(lane)
+}
+
+// One lane's server, held open until `stop` — a lane that could not be served is traced, never thrown,
+// so it costs the supervisor nothing but that lane's broker.
+async function hold_server(lane: LaneInfo, held: Promise<void>): Promise<void> {
+	try {
+		await lane_session_broker.with_server(lane, async () => {
+			await held
+		})
+	} catch (error) {
+		error_text.trace_swallowed('claude_lane_broker.hold_server', error)
+	}
+}
+
+function serve_lane(lane: LaneInfo): Served {
+	const release = { stop: (): void => undefined }
+	const held = new Promise<void>((resolve) => {
+		release.stop = resolve
+	})
+
+	return { stop: release.stop, done: hold_server(lane, held) }
+}
+
+// **A closed lane's entry stays until its server has finished.** A server still answering a reviewer
+// keeps writing its response, so a server opened beside it for a re-listed lane would have the two
+// overwrite each other — the lane is reopened only by the scan after the old one is gone.
+async function forget_when_done(
+	served: Map<string, Served>,
+	issue: string,
+	entry: Served,
+): Promise<void> {
+	await entry.done
+	if (served.get(issue) === entry) served.delete(issue)
+}
+
+function close_gone(served: Map<string, Served>, open: ReadonlySet<string>): void {
+	for (const [issue, entry] of served) {
+		if (open.has(issue)) {
+			continue
+		}
+
+		entry.stop()
+		void forget_when_done(served, issue, entry)
+	}
+}
+
+function open_new(served: Map<string, Served>, lanes: ReadonlyArray<LaneInfo>): void {
+	for (const lane of lanes) {
+		if (!served.has(lane.issue)) served.set(lane.issue, serve_lane(lane))
+	}
+}
+
+async function scan(served: Map<string, Served>, list: ListLanes): Promise<void> {
+	try {
+		const listed = await list()
+		const lanes = listed.filter((lane) => is_served(lane))
+
+		close_gone(served, new Set(lanes.map((lane) => lane.issue)))
+		open_new(served, lanes)
+	} catch (error) {
+		error_text.trace_swallowed('claude_lane_broker.scan', error)
+	}
+}
+
+// Each scan starts only once the previous one has finished, so two never race over the same map.
+async function scan_after(
+	previous: Promise<void>,
+	served: Map<string, Served>,
+	list: ListLanes,
+): Promise<void> {
+	await previous
+	await scan(served, list)
+}
+
+// Starts serving now and on every interval; the returned stop closes every server and waits for them.
+function start(list: ListLanes = lane_registry.list_lanes): () => Promise<void> {
+	const served = new Map<string, Served>()
+	const state = { scanning: scan(served, list) }
+	const timer = setInterval(() => {
+		state.scanning = scan_after(state.scanning, served, list)
+	}, SCAN_INTERVAL_MS).unref()
+
+	return async () => {
+		clearInterval(timer)
+		await state.scanning
+		close_gone(served, new Set())
+		await Promise.all(
+			[...served.values()].map(async (entry) => {
+				await entry.done
+			}),
+		)
+	}
+}
+
+// Serves every open Claude lane for exactly as long as `run` runs.
+async function serve_during<T>(
+	run: () => Promise<T>,
+	list: ListLanes = lane_registry.list_lanes,
+): Promise<T> {
+	const stop = start(list)
+
+	try {
+		return await run()
+	} finally {
+		await stop()
+	}
+}
+
+const claude_lane_broker = { SCAN_INTERVAL_MS, serve_during, start }
+
+export { claude_lane_broker }

package/scripts/lane/lane-await.ts

@@ -12,6 +12,7 @@ import {
 } from '#scripts/run/run-liveness'
 import { lane_child_invocation } from './lane-child-invocation'
 import { lane_handoff } from './lane-handoff'
+import { process_tools } from './process-tools'
 
 // Detached lane children are not harness-tracked processes, so their completion fires no
 // re-invocation event in the parent's session. Without a blocking wait the parent notices only
@@ -30,6 +31,7 @@ const NEVER_APPEARED_TIMEOUT_MS = 600_000
 const MS_PER_SECOND = 1000
 const PROCESS_FOUND = 0
 const PROCESS_NOT_FOUND = 1
+const PGREP_COMMAND = 'pgrep'
 
 // `is_settled` is read once, when the wait starts: a child that ended between two `lane:await` calls
 // never appears in the second one, and only its settled issue tells it apart from one not yet
@@ -77,14 +79,16 @@ interface RunConfig extends CheckConfig {
 
 // Three answers, not two: only pgrep's own "no match" exit is `none`. A pgrep that failed or hit its
 // timeout never looked, and `run:liveness` answers `undetermined` for it rather than booking a live
-// child as stopped.
+// child as stopped. A pgrep that is not installed could never look, so it is refused by name.
 function process_trace_default(issue: string): ProcessTrace {
 	const pattern = lane_child_invocation.process_pattern(issue)
-	const result = spawnSync('pgrep', ['-f', pattern], {
+	const result = spawnSync(PGREP_COMMAND, ['-f', pattern], {
 		encoding: 'utf8',
 		timeout: PROBE_TIMEOUT_MS,
 	})
 
+	process_tools.throw_if_missing(PGREP_COMMAND, result.error)
+
 	if (result.status === PROCESS_FOUND) return PROCESS_ALIVE
 	if (lane_handoff.is_ship_running(issue, process.cwd())) return PROCESS_ALIVE
 

package/scripts/lane/lane-cache.ts

@@ -1,5 +1,13 @@
 import { randomUUID } from 'node:crypto'
-import { cpSync, existsSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import {
+	cpSync,
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	renameSync,
+	rmSync,
+	writeFileSync,
+} from 'node:fs'
 import path from 'node:path'
 import { hook_launch } from '#scripts/init/hook-launch'
 import {
@@ -30,6 +38,8 @@ import {
 // checkout never produced is skipped, and a copy that fails is skipped rather than thrown — so
 // seeding can never be the reason an open fails, unlike the `.env` write the lane cannot run without.
 
+const STAGING_SEGMENTS = ['node_modules', '.cache', 'josh-lane-cache'] as const
+
 function replace_root(value: unknown, source_prefix: string, destination_root: string): unknown {
 	if (typeof value !== 'string') return value
 
@@ -61,19 +71,39 @@ function portable_content(
 	return content
 }
 
-function write_atomically(destination_path: string, content: string): void {
-	const temporary_path = `${destination_path}.${String(process.pid)}.${randomUUID()}.tmp`
+// The staging file lives under `node_modules/.cache`, never beside the cache it replaces: prettier
+// runs in parallel with the tool whose cache is being copied, and a temporary name in the checkout
+// root is listed by its tree walk and gone by the time it is read (#3763). `node_modules` is skipped
+// by every tree scan and sits on the checkout's own filesystem, so the rename stays atomic.
+function stage_path(destination_root: string, cache_file: string): string {
+	const staging_directory = path.join(destination_root, ...STAGING_SEGMENTS)
+
+	mkdirSync(staging_directory, { recursive: true })
+
+	return path.join(staging_directory, `${cache_file}.${String(process.pid)}.${randomUUID()}.tmp`)
+}
 
+function publish_staged(temporary_path: string, destination_path: string, content: string): void {
 	try {
 		writeFileSync(temporary_path, content, { flag: 'wx' })
 		renameSync(temporary_path, destination_path)
-	} catch {
-		// Best-effort: a cache that could not be published simply leaves the destination unchanged.
 	} finally {
 		rmSync(temporary_path, { force: true })
 	}
 }
 
+function write_atomically(destination_root: string, cache_file: string, content: string): void {
+	if (!existsSync(destination_root)) return
+
+	try {
+		const temporary_path = stage_path(destination_root, cache_file)
+
+		publish_staged(temporary_path, path.join(destination_root, cache_file), content)
+	} catch {
+		// Best-effort: a cache that could not be published simply leaves the destination unchanged.
+	}
+}
+
 function copy_if_present(source_root: string, destination: string, spec: GateCacheSpec): void {
 	const source_path = path.join(source_root, spec.cache_file)
 	if (!existsSync(source_path)) return
@@ -86,7 +116,7 @@ function copy_if_present(source_root: string, destination: string, spec: GateCac
 			destination,
 		)
 
-		write_atomically(path.join(destination, spec.cache_file), content)
+		write_atomically(destination, spec.cache_file, content)
 	} catch {
 		// A missing, changing, or malformed cache is a miss, never a failed lane or gate.
 	}
@@ -130,6 +160,6 @@ function sync_cache(source_root: string, destination: string, cache_file: string
 	copy_if_present(source_root, destination, spec)
 }
 
-const lane_cache = { seed_caches, seed_hook_bundles, sync_cache }
+const lane_cache = { STAGING_SEGMENTS, seed_caches, seed_hook_bundles, sync_cache }
 
 export { lane_cache }

package/scripts/lane/lane-capacity.ts

@@ -10,14 +10,16 @@ import { lane_seed_policy } from './lane-seed'
 // is what would have to be undone the first time two epics run together, which is why the scheduler
 // is epic-free.
 //
-// **It is a ceiling, not a prediction.** Six lanes does not say six children will run at once; it
-// says a seventh will not start. What actually runs is bounded by what is runnable, by the port
+// **It is a ceiling, not a prediction.** Four lanes does not say four children will run at once; it
+// says a fifth will not start. What actually runs is bounded by what is runnable, by the port
 // seats `lane-seed.ts` can allocate, and by the machine.
 
-// Six rather than the nine seats `lane_seed_policy` can allocate: the seats are the hard structural
+// Four rather than the nine seats `lane_seed_policy` can allocate: the seats are the hard structural
 // bound, this is the one a person tunes, and leaving headroom between them means raising the limit
-// never lands on "the ports ran out" as its first symptom.
-const DEFAULT_LANE_LIMIT = 6
+// never lands on "the ports ran out" as its first symptom. joshuafolkken/kit#3788 lowered it from
+// six: a week of `lane:stats` showed 1.5 effective lanes, while the hours at five or six lanes held
+// the swap peak, the slowest gates and most of the gate and commit failures.
+const DEFAULT_LANE_LIMIT = 4
 const LANE_LIMIT_KEY = 'JOSH_LANE_LIMIT'
 const POSITIVE_INTEGER = /^[1-9]\d*$/u
 const NO_LANES = 0
@@ -28,7 +30,7 @@ const NO_LANES = 0
 type LimitChoice = { kind: 'limit'; limit: number } | { kind: 'problem'; problem: string }
 
 // **An invalid value is a hard error, never a silent fall back to the default** — the rule
-// `PORT_SEED` already holds to. A typo that quietly becomes 6 is a limit nobody set, and the whole
+// `PORT_SEED` already holds to. A typo that quietly becomes 4 is a limit nobody set, and the whole
 // point of the setting is that the number is the one a person chose.
 //
 // Blank is unset, not invalid: an `.env` line left as `JOSH_LANE_LIMIT=` is a variable nobody

package/scripts/lane/lane-child-invocation.ts

@@ -85,4 +85,5 @@ const lane_child_invocation = {
 	ship_stop_invocation,
 }
 
+export type { ShipStop }
 export { lane_child_invocation }

package/scripts/lane/lane-cli.ts

@@ -18,6 +18,7 @@ import { lane_output, type ReadOutcome, type RecordOutcome } from './lane-output
 import { lane_registry, type LaneInfo } from './lane-registry'
 import { lane_report } from './lane-report'
 import { lane_seed_policy } from './lane-seed'
+import type { KeptLane } from './lane-spent'
 import { lane_stray } from './lane-stray'
 
 // `josh lane:open` / `lane:close` / `lane:list` / `lane:prune` — the lane's whole lifecycle.
@@ -263,10 +264,23 @@ async function list_command(rest: ReadonlyArray<string>): Promise<number> {
 	return code
 }
 
+// A lane left open is named with its reason, so a person can tell a lane somebody is in from one that
+// only waits on a push, a commit or an issue — and knows the command that discards it anyway.
+function report_kept(kept: ReadonlyArray<KeptLane>): void {
+	for (const lane of kept) {
+		console.error(
+			`Kept the lane for ${session_cite.issue(lane.issue)}: ${lane.reason}. \`pnpm josh lane:close ${lane.issue}\` discards it.`,
+		)
+	}
+}
+
 async function prune_command(rest: ReadonlyArray<string>): Promise<number> {
 	if (rest.length > 0) return report_usage()
 
-	const code = report_sweep(await lane_close.prune_lanes())
+	const outcome = await lane_close.prune_lanes()
+	const code = report_sweep(outcome)
+
+	report_kept(outcome.kept)
 
 	// After the closes, so a lane whose close left its directory behind is swept in the same run. A
 	// kept stray is reported, never a failure: it waits on a person, and a non-zero exit would stop

package/scripts/lane/lane-close.ts

@@ -5,6 +5,7 @@ import { error_text } from '#scripts/lib/error-message'
 import { lane_paths } from './lane-paths'
 import { lane_reap } from './lane-reap'
 import { lane_registry, type LaneInfo } from './lane-registry'
+import { lane_spent, type KeptLane } from './lane-spent'
 
 // Closing a lane: no work tree, no branch, no directory.
 //
@@ -42,6 +43,11 @@ interface SweepOutcome {
 	failed: Array<string>
 }
 
+interface PruneOutcome extends SweepOutcome {
+	// The live lanes left open, each with the reason it was not discarded.
+	kept: Array<KeptLane>
+}
+
 async function ignore_failure(action: () => Promise<string>): Promise<void> {
 	try {
 		await action()
@@ -171,14 +177,17 @@ async function close_each(issues: ReadonlyArray<string>): Promise<SweepOutcome>
 }
 
 /**
- * Close every lane whose work tree is no longer on disk — the route out of an interruption that took
- * the directory with it and left git's registration behind.
+ * Close every lane nothing needs any more: one whose work tree is no longer on disk — the route out of
+ * an interruption that took the directory with it and left git's registration behind — and one a past
+ * run left spent (`lane-spent.ts`). A live lane that is not spent is kept, and `kept` says why.
  */
-async function prune_lanes(): Promise<SweepOutcome> {
+async function prune_lanes(): Promise<PruneOutcome> {
 	const lanes = await lane_registry.list_lanes()
-	const stranded = lanes.filter((lane) => lane.is_stranded)
+	const { spent, kept } = await lane_spent.sort_lanes(lanes)
+	const doomed = lanes.filter((lane) => lane.is_stranded || spent.includes(lane))
+	const sweep = await close_each(doomed.map((lane) => lane.issue))
 
-	return await close_each(stranded.map((lane) => lane.issue))
+	return { ...sweep, kept }
 }
 
 async function close_all_lanes(): Promise<SweepOutcome> {
@@ -194,5 +203,5 @@ const lane_close = {
 	resolve_lane,
 }
 
-export type { CloseKind, CloseOutcome, ResolvedLane, SweepOutcome }
+export type { CloseKind, CloseOutcome, PruneOutcome, ResolvedLane, SweepOutcome }
 export { lane_close }

package/scripts/lane/lane-dispatch.ts

@@ -49,6 +49,7 @@ const WARNING_RECOVERY =
 // The discriminant for a dispatch refused because the `in-progress` marker could not be applied, named
 // once rather than inlined at each use.
 const LABEL_UNSET_KIND = 'label-unset'
+const RESTART_START = 'restart'
 // The role a lane child runs under, resolved once so the fresh and resume builders read the same one.
 const RESOLVED_ROLE = agent_role_profile.WORKER
 
@@ -281,13 +282,15 @@ function built_for(plan: ResumePlan, profile: AgentProfile, lane: LaneInfo): Age
 // **The re-dispatch decides resume-or-fresh from the lane's own exit record**.
 // The record is read from the log the previous dispatch of this lane wrote — a first dispatch finds
 // none and starts fresh, an `outage` ending with a session id resumes it. The provider is resolved
-// first because the resume mechanism is Claude Code's, and an OpenAI lane falls back to fresh.
-function prepared(lane: LaneInfo): Prepared {
+// first because the resume mechanism is Claude Code's, and an OpenAI lane falls back to fresh. **A
+// fresh dispatch never reads the record**: a person restarting a child (`lane:restart`) wants a new
+// session that reads the Issue from the start, whatever the previous one ended on.
+function prepared(lane: LaneInfo, is_fresh: boolean): Prepared {
 	const resolved = agent_role_profile.resolve(RESOLVED_ROLE)
 
 	if (resolved.kind === 'rejected') return resolved
 
-	const record = run_ending.read_exit(default_log_path(lane))
+	const record = is_fresh ? undefined : run_ending.read_exit(default_log_path(lane))
 	const plan = lane_resume.plan(lane.issue, record, resolved.profile.provider)
 	const built = built_for(plan, resolved.profile, lane)
 
@@ -333,8 +336,23 @@ async function record_started(issue: string): Promise<void> {
 	await lane_ledger.record_dispatch(Number(issue))
 }
 
-async function finish_dispatch(issue: string, request: StartRequest): Promise<DispatchOutcome> {
-	const mark = await mark_in_progress(issue)
+// How a dispatch begins. A `resumable` one claims the marker itself and resumes an `outage` session; a
+// `restart` is a person's (`lane:restart`): its caller claimed the marker before stopping the old child,
+// so no GitHub round-trip sits between that stop and this launch, and the session starts fresh.
+type DispatchStart = 'resumable' | typeof RESTART_START
+
+async function claimed(issue: string, start: DispatchStart): Promise<LabelWrite> {
+	if (start === RESTART_START) return { is_applied: true }
+
+	return await mark_in_progress(issue)
+}
+
+async function finish_dispatch(
+	issue: string,
+	request: StartRequest,
+	start: DispatchStart,
+): Promise<DispatchOutcome> {
+	const mark = await claimed(issue, start)
 
 	if (!mark.is_applied) return { kind: LABEL_UNSET_KIND, reason: mark.reason }
 	const outcome = await started(request)
@@ -346,14 +364,21 @@ async function finish_dispatch(issue: string, request: StartRequest): Promise<Di
 	return outcome
 }
 
-/** Start `fullrun #<N>` detached in the lane for `#<N>`, recording where it writes as it does so. */
-async function dispatch_child(issue: string): Promise<DispatchOutcome> {
+/**
+ * Start `fullrun #<N>` detached in the lane for `#<N>`, recording where it writes as it does so.
+ * A `restart` start expects the marker already claimed and starts a new session even where the lane's
+ * last ending would resume one.
+ */
+async function dispatch_child(
+	issue: string,
+	start: DispatchStart = 'resumable',
+): Promise<DispatchOutcome> {
 	issue_number_shape.require_issue_number(issue)
 
 	const lane = await lane_registry.find_open_lane(issue)
 
 	if (lane === undefined) return { kind: 'no-lane' }
-	const built = prepared(lane)
+	const built = prepared(lane, start === RESTART_START)
 	const log_path = default_log_path(lane)
 
 	if (built.kind === 'rejected') return { kind: 'failed', lane, log_path, note: built.note }
@@ -362,7 +387,7 @@ async function dispatch_child(issue: string): Promise<DispatchOutcome> {
 
 	if (log.kind !== 'ready') return log
 
-	return await finish_dispatch(issue, { lane, log_path: log.path, ...built })
+	return await finish_dispatch(issue, { lane, log_path: log.path, ...built }, start)
 }
 
 // **A launch whose log could not be opened is still a launch, and the reader has to hear both halves.**
@@ -438,6 +463,7 @@ async function warn_of_problem(outcome: DispatchOutcome, issue: string): Promise
 
 const lane_dispatch = {
 	child_invocation,
+	claim_marker: mark_in_progress,
 	default_log_path,
 	describe,
 	dispatch_child,
@@ -446,5 +472,5 @@ const lane_dispatch = {
 	warn_of_problem,
 }
 
-export type { DispatchOutcome }
+export type { DispatchOutcome, DispatchStart }
 export { lane_dispatch }

package/scripts/lane/lane-environment.ts

@@ -7,7 +7,7 @@ import { agent_role_profile, type AgentProfile } from '#scripts/agent/agent-role
 // the nearest ancestor holding a `package.json` — which, inside a linked work tree, is the lane's
 // own directory — so a lane with no `.env` runs on seed 0 and a lane handed a verbatim copy of the
 // root's runs on the root's exact offset; either way every lane lands on one pair of ports, and a
-// busy port fails without retrying on another. At the default six lanes that turns E2E from "fails
+// busy port fails without retrying on another. At six lanes that turns E2E from "fails
 // sometimes" into "fails nearly always". So the lane's `.env` keeps the project's `PORT_SEED`
 // unchanged and adds `JOSH_LANE_SEAT`, and `ports/index.js` combines them as `seed × 10 + seat`:
 // the file plainly shows which number is the project's and which is the

package/scripts/lane/lane-launch-cli.ts

@@ -6,6 +6,7 @@ import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
 import { lane_vacant } from '#scripts/lane/lane-vacant'
 import { cli_flags } from '#scripts/lib/cli-flags'
 import { INSTALL_TIMEOUT_MS } from '#scripts/lib/timeouts'
+import { run_event_setup } from '#scripts/run/event/run-event-setup'
 import { execa } from 'execa'
 
 // `josh lane:launch <issue> [--stash <message>]` — one composite command for a `backlogrun` lane-start
@@ -73,8 +74,11 @@ async function install(directory: string): Promise<boolean> {
 
 // The first lane pops the shared stash and re-installs against the lock it brought in; a pop that
 // refused (`no-match` / `ambiguous`) stops the lane rather than dispatching onto an unprepared tree.
-// A caller without `--stash` skips both, which is every lane after the first.
-async function prepare(stash: string | undefined, directory: string): Promise<boolean> {
+// A caller without `--stash` skips both, which is every lane after the first. The re-install is a
+// stage of its own on the run's stream, as the install `lane:open` ran was.
+async function prepare(context: LaunchContext, directory: string): Promise<boolean> {
+	const { issue, stash } = context
+
 	if (stash === undefined) return true
 
 	const popped = await josh_command.josh_run(
@@ -84,6 +88,8 @@ async function prepare(stash: string | undefined, directory: string): Promise<bo
 
 	if (popped.code !== SUCCESS_EXIT_CODE) return false
 
+	await run_event_setup.emit(run_event_setup.installing(issue))
+
 	return await install(directory)
 }
 
@@ -124,13 +130,16 @@ async function lane_directory(issue: string): Promise<string | undefined> {
 }
 
 // The launch chain in-process. The CLI prints the pid; `backlog:drive` launches through this same
-// chain.
+// chain. The dispatch is said on the run's stream before it starts, so the board draws a lane that is
+// ready apart from one still being filled.
 async function launch_lane(context: LaunchContext): Promise<LaunchOutcome> {
 	const directory = await lane_directory(context.issue)
 
 	if (directory === undefined) return UNOPENED
 
-	if (!(await prepare(context.stash, directory))) return FAILED
+	if (!(await prepare(context, directory))) return FAILED
+
+	await run_event_setup.emit(run_event_setup.dispatching(context.issue))
 
 	const dispatched = await josh_command.josh_run(
 		['lane:dispatch', context.issue],