@joshuafolkken/kit 1.1387.0 → 1.1435.0

package/scripts/lane/lane-ledger.ts

@@ -5,8 +5,8 @@ import { run_carry } from '#scripts/run/carry/run-carry'
 import { z } from 'zod'
 
 // The measurement ledger the lane limit is tuned against: one JSON line per
-// lane merge, per finished `josh gate`, per machine-load sample, per lane dispatch and per finished
-// `josh ship` stage, read back by `josh lane:stats`.
+// lane merge, per finished `josh gate`, per machine-load sample, per lane dispatch, per finished
+// `josh ship` stage and per stopped `josh ship`, read back by `josh lane:stats`.
 //
 // **Its own file rather than the run's event stream.** The stream is capped at 500 events and is
 // rewritten whole on every append, which is right for "where is the run" and wrong for a measurement
@@ -35,6 +35,7 @@ const KIND = {
 	LOAD: 'load',
 	DISPATCH: 'dispatch',
 	STAGE: 'stage',
+	STOP: 'stop',
 } as const
 
 const merge_schema = z.object({ kind: z.literal(KIND.MERGE), at: z.string(), issue: z.number() })
@@ -79,12 +80,22 @@ const stage_schema = z.object({
 	elapsed_ms: z.number(),
 	issue: z.number().optional(),
 })
+// A `josh ship` that stopped on `issue`: `reason` is the stage it stopped at, or `conflict` — the
+// retrospective's stop reason. How long it stayed stopped is derived from the next ship stage, not
+// recorded, so a resumed ship never has to know the stop it ends.
+const stop_schema = z.object({
+	kind: z.literal(KIND.STOP),
+	at: z.string(),
+	issue: z.number(),
+	reason: z.string(),
+})
 const entry_schema = z.discriminatedUnion('kind', [
 	merge_schema,
 	gate_schema,
 	load_schema,
 	dispatch_schema,
 	stage_schema,
+	stop_schema,
 ])
 
 type LedgerEntry = z.infer<typeof entry_schema>
@@ -93,9 +104,11 @@ type GateEntry = z.infer<typeof gate_schema>
 type LoadEntry = z.infer<typeof load_schema>
 type DispatchEntry = z.infer<typeof dispatch_schema>
 type StageEntry = z.infer<typeof stage_schema>
+type StopEntry = z.infer<typeof stop_schema>
 // What a finished gate reports; the ledger stamps the kind and the time.
 type GateRecord = Omit<GateEntry, 'kind' | 'at'>
 type StageRecord = Omit<StageEntry, 'kind' | 'at'>
+type StopRecord = Omit<StopEntry, 'kind' | 'at'>
 
 function target_of(repository: string): string {
 	return stamp_file.stamp_path(LEDGER_PREFIX, repository, LEDGER_SUFFIX)
@@ -168,6 +181,10 @@ async function record_stage(stage: StageRecord, path?: string): Promise<void> {
 	await record({ kind: KIND.STAGE, at: now_iso(), ...stage }, path)
 }
 
+async function record_stop(stop: StopRecord, path?: string): Promise<void> {
+	await record({ kind: KIND.STOP, at: now_iso(), ...stop }, path)
+}
+
 function parse_line(line: string): LedgerEntry | undefined {
 	return entry_schema.safeParse(json_value.parse_or_undefined(line)).data
 }
@@ -199,9 +216,10 @@ const lane_ledger = {
 	record_gate,
 	record_merge,
 	record_stage,
+	record_stop,
 	target,
 	target_of,
 }
 
-export type { DispatchEntry, GateEntry, LedgerEntry, LoadEntry, MergeEntry, StageEntry }
+export type { DispatchEntry, GateEntry, LedgerEntry, LoadEntry, MergeEntry, StageEntry, StopEntry }
 export { lane_ledger }

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

@@ -7,12 +7,14 @@ import { lane_ledger } from './lane-ledger'
 import { lane_sampler, type MeasureContext } from './lane-sampler'
 import { lane_stage_stats } from './lane-stage-stats'
 import { lane_stats } from './lane-stats'
+import { lane_stop_stats } from './lane-stop-stats'
 
 // `josh lane:sample` / `josh lane:stats` — the lane-limit measurement.
 //
 // `lane:sample` appends one machine-load sample to the ledger, or one every `--every <seconds>` until it
 // is stopped; `lane:stats` reduces a period of the ledger to the one table row #3347 records per lane
-// limit, and under it the per-stage durations of the period's lanes. Every entry writes itself during
+// limit, under it the per-stage durations of the period's lanes, and under those how long a stopped
+// ship waited for each stop reason. Every entry writes itself during
 // a `backlogrun` — the merges, the gates, the stages, and the load `backlog:drive` samples while it
 // runs — so a person only closes the period with `lane:stats`; `lane:sample` is for a load reading
 // outside one. The procedure is `docs/maintainers/lane-limit-measurement.md`.
@@ -112,7 +114,13 @@ async function stats_command(
 	const entries = await read_ledger(context)
 	const row = lane_stats.row(entries, window, label)
 
-	console.info(`${lane_stats.header()}\n${row}\n\n${lane_stage_stats.table(entries, window)}`)
+	console.info(
+		[
+			`${lane_stats.header()}\n${row}`,
+			lane_stage_stats.table(entries, window),
+			lane_stop_stats.table(entries, window),
+		].join('\n\n'),
+	)
 
 	return 0
 }

package/scripts/lane/lane-open.ts

@@ -4,6 +4,7 @@ import { ENV_FILE_NAME } from '#ports'
 import { git_worktree } from '#scripts/git/git-worktree'
 import { session_cite } from '#scripts/issue/session-cite'
 import { file_reader } from '#scripts/lib/read-file'
+import { run_event_setup } from '#scripts/run/event/run-event-setup'
 import { lane_cache } from './lane-cache'
 import { lane_environment } from './lane-environment'
 import { lane_install, type InstallResult } from './lane-install'
@@ -172,6 +173,13 @@ function guard_install(lane: LaneInfo, result: InstallResult): void {
 	)
 }
 
+// **The install is said on the run's stream as it starts**: it is the long part of opening a lane, and
+// `run:board` draws it apart from the work tree being made. Best-effort, as every stage is.
+async function fill(lane: LaneInfo): Promise<void> {
+	await run_event_setup.emit(run_event_setup.installing(lane.issue))
+	guard_install(lane, await lane_install.install_dependencies(lane.directory))
+}
+
 function build_plan(
 	repository_root: string,
 	root: string,
@@ -231,7 +239,7 @@ async function materialize(plan: LanePlan, source_root: string): Promise<void> {
 		release_seat_lock(plan.seat_lock)
 		lane_cache.seed_caches(source_root, plan.lane.directory)
 		lane_cache.seed_hook_bundles(source_root, plan.lane.directory)
-		guard_install(plan.lane, await lane_install.install_dependencies(plan.lane.directory))
+		await fill(plan.lane)
 	} finally {
 		release_seat_lock(plan.seat_lock)
 	}

package/scripts/lane/lane-preserve.ts

@@ -0,0 +1,49 @@
+import { git_gh_issue_write } from '#scripts/gh/git-gh-issue-write'
+import { git_stash } from '#scripts/git/stash/git-stash'
+
+// Keeping a lane's uncommitted work before something discards or restarts it — `run:merge` closing a
+// lane, `lane:restart` handing it to a fresh session. The stash stack outlives the tree, so the push is
+// the copy, and the comment on the Issue is where a person finds it again. One writer, so the message
+// `stash:pop` matches on and the recovery line the comment names cannot drift between the callers.
+
+function preserved_comment(message: string, cause: string): string {
+	return [
+		`The lane held uncommitted work when ${cause}, so it was stashed:`,
+		`- recover with \`pnpm josh stash:pop "${message}"\``,
+	].join('\n')
+}
+
+/**
+ * Push the lane's uncommitted work under `<issue>: uncommitted work at <occasion>`, and return the
+ * message. A push that fails throws, so the caller keeps the tree rather than losing it.
+ */
+async function push_work(issue: string, directory: string, occasion: string): Promise<string> {
+	const message = git_stash.work_message(issue, occasion)
+
+	await git_stash.push(message, directory)
+
+	return message
+}
+
+/** Say on the Issue where the stash `message` went, `cause` completing "when …". Never throws. */
+async function announce(issue: string, message: string, cause: string): Promise<void> {
+	await git_gh_issue_write.issue_try_comment(issue, preserved_comment(message, cause))
+}
+
+/** `push_work`, then `announce` — for a caller with no reason to separate the two. */
+async function stash_work(
+	issue: string,
+	directory: string,
+	occasion: string,
+	cause: string,
+): Promise<string> {
+	const message = await push_work(issue, directory, occasion)
+
+	await announce(issue, message, cause)
+
+	return message
+}
+
+const lane_preserve = { announce, push_work, stash_work }
+
+export { lane_preserve }

package/scripts/lane/lane-reap.ts

@@ -1,6 +1,7 @@
 import { execFileSync } from 'node:child_process'
 import { PROBE_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { lane_child_invocation } from './lane-child-invocation'
+import { process_tools } from './process-tools'
 
 // Ending a lane child that did not end itself.
 //
@@ -42,7 +43,9 @@ function parse_pids(printed: string): Array<number> {
 		.filter((pid) => Number.isSafeInteger(pid) && pid >= LOWEST_CHILD_PID)
 }
 
-// `pgrep` exits 1 when nothing matches, which `execFileSync` throws — the empty list either way.
+// `pgrep` exits 1 when nothing matches, which `execFileSync` throws — the empty list either way. A
+// probe that is not installed is refused by name: reading it as "nothing there" is how a missing `ps`
+// left the owner check answering `unknown`.
 function run_probe(command: string, args: ReadonlyArray<string>): string {
 	try {
 		return execFileSync(command, [...args], {
@@ -50,7 +53,9 @@ function run_probe(command: string, args: ReadonlyArray<string>): string {
 			timeout: PROBE_TIMEOUT_MS,
 			stdio: ['ignore', 'pipe', 'ignore'],
 		})
-	} catch {
+	} catch (error) {
+		process_tools.throw_if_missing(command, error)
+
 		return ''
 	}
 }
@@ -111,6 +116,12 @@ function tree_of(roots: ReadonlyArray<number>, probes: ReapProbes): Array<number
 	return tree
 }
 
+function roots_of(issue: string, own: Set<number>, probes: ReapProbes): 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
@@ -118,14 +129,18 @@ function tree_of(roots: ReadonlyArray<number>, probes: ReapProbes): Array<number
  */
 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))
+	const doomed = tree_of(roots_of(issue, own, probes), probes).filter((pid) => !own.has(pid))
 
 	return doomed.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 {
+	return roots_of(issue, own_ancestry(probes), probes).length > 0
+}
+
 const lane_reap = {
+	is_child_running,
 	own_ancestry,
 	parse_pids,
 	reap_child,

package/scripts/lane/lane-registry.ts

@@ -236,6 +236,11 @@ async function has_lanes_in_flight(): Promise<boolean> {
 	return lanes.some((lane) => !lane.is_stranded)
 }
 
+/** The lanes in use: the open work trees an interruption has not stranded. */
+function live_count(lanes: ReadonlyArray<LaneInfo>): number {
+	return lanes.filter((lane) => !lane.is_stranded).length
+}
+
 /** The seats live lanes hold — what a new lane's seat has to avoid. */
 function used_seats(lanes: ReadonlyArray<LaneInfo>): Array<number> {
 	return lanes.map((lane) => lane.seat).filter((seat): seat is number => seat !== undefined)
@@ -267,6 +272,7 @@ const lane_registry = {
 	find_open_lane,
 	has_lanes_in_flight,
 	list_lanes,
+	live_count,
 	main_repository_root,
 	parse_block,
 	read_environment,

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

@@ -0,0 +1,51 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { lane_dispatch } from './lane-dispatch'
+import { lane_restart, type RestartOutcome } from './lane-restart'
+
+// `josh lane:restart <issue>` — the contract `lane:dispatch` sets: the fresh child's pid is the one
+// token on standard output, every explanation on standard error, and a restart that did not start a
+// fresh child exits non-zero. A failed dispatch is warned off-screen exactly as `lane:dispatch` warns it,
+// since the stopped child is then left for `run:merge` to collect.
+
+const ARGV_OFFSET = 2
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const USAGE = 'Usage: josh lane:restart <issue-number>'
+
+async function report(outcome: RestartOutcome, issue: string): Promise<number> {
+	console.error(lane_restart.describe(outcome, issue))
+
+	if (outcome.kind !== 'restarted') return FAILURE_EXIT_CODE
+	const { dispatch } = outcome
+
+	if (lane_dispatch.is_worth_warning(dispatch)) await lane_dispatch.warn_of_problem(dispatch, issue)
+	if (dispatch.kind !== 'dispatched') return FAILURE_EXIT_CODE
+
+	console.info(String(dispatch.pid))
+
+	return SUCCESS_EXIT_CODE
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const issue = argv.length === 1 ? argv[0] : undefined
+
+	if (issue === undefined || !issue_number_shape.is_issue_number(issue)) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	return await report(await lane_restart.restart(issue), issue)
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const lane_restart_cli = { run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { lane_restart_cli }

package/scripts/lane/lane-restart.ts

@@ -0,0 +1,175 @@
+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'
+import { session_cite } from '#scripts/issue/session-cite'
+import { error_text } from '#scripts/lib/error-message'
+import { run_cut } from '#scripts/run/cut/run-cut'
+import { run_event_stream } from '#scripts/run/event/run-event-stream'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
+import { lane_dispatch, type DispatchOutcome } from './lane-dispatch'
+import { lane_preserve } from './lane-preserve'
+import { lane_reap } from './lane-reap'
+import { lane_registry, type LaneInfo } from './lane-registry'
+
+// `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
+// 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.
+//
+// **No GitHub round-trip sits between the stop and the launch**, since one slow answer would outlast the
+// window. The `in-progress` marker is claimed while the old child still runs — a refused claim stops
+// nothing — and the Issue comment naming the stash is posted after the fresh child is up.
+//
+// The fresh dispatch reads no exit record (an outage record would otherwise resume the stopped session),
+// a carried cut is ended (its successor would adopt the old hand-off), and the work in the tree is
+// stashed with the recovery line on the Issue. The `restart` event follows the dispatch's own
+// `child-launch`, so the stream and `run:board` say a person restarted the child.
+
+const RESTART_OCCASION = 'lane restart'
+const RESTART_CAUSE = 'a person restarted its child with `lane:restart`'
+const DISPATCHED_KIND = 'dispatched'
+const NO_LANE_KIND = 'no-lane'
+const NOT_RUNNING_KIND = 'not-running'
+const UNCLAIMED_KIND = 'unclaimed'
+
+interface Unsaved {
+	kind: 'unsaved'
+	directory: string
+	reason: string
+}
+
+interface Restarted {
+	kind: 'restarted'
+	dispatch: DispatchOutcome
+	stash: string | undefined
+}
+
+type Refused =
+	| { kind: typeof NO_LANE_KIND }
+	| { kind: typeof NOT_RUNNING_KIND }
+	| { kind: typeof UNCLAIMED_KIND; reason: string }
+type RestartOutcome = Restarted | Unsaved | Refused
+type Saved = Unsaved | { kind: 'saved'; stash: string | undefined }
+
+// A cut the stopped child carried would hand its successor the old session's hand-off at
+// `run:cut --resume`; the fresh session has to start from the Issue instead.
+function end_carried_cut(lane: LaneInfo): void {
+	const carried = run_cut.lane_cut_sync(lane.directory)
+
+	if (carried !== undefined) run_cut.end_cut(carried.target)
+}
+
+async function stash_of(lane: LaneInfo): Promise<string | undefined> {
+	if (!(await git_stash.has_changes(lane.directory))) return undefined
+
+	return await lane_preserve.push_work(lane.issue, lane.directory, RESTART_OCCASION)
+}
+
+// A tree that could not be read or pushed is left as it is: re-dispatching into it would hand the fresh
+// session the stopped one's half-done work as though it were its own.
+async function save_work(lane: LaneInfo): Promise<Saved> {
+	try {
+		return { kind: 'saved', stash: await stash_of(lane) }
+	} catch (error) {
+		return { kind: 'unsaved', directory: lane.directory, reason: error_text.message_of(error) }
+	}
+}
+
+async function record_restart(issue: string): Promise<void> {
+	await run_event_stream_emit.emit(
+		run_event_stream.EVENT_KIND.RESTART,
+		`${issue_cite.plain(issue)} restarted in a fresh session by a person`,
+	)
+}
+
+async function relaunch(lane: LaneInfo): Promise<RestartOutcome> {
+	end_carried_cut(lane)
+	const saved = await save_work(lane)
+
+	if (saved.kind === 'unsaved') return saved
+	const dispatch = await lane_dispatch.dispatch_child(lane.issue, 'restart')
+
+	if (dispatch.kind === DISPATCHED_KIND) await record_restart(lane.issue)
+
+	if (saved.stash !== undefined) {
+		await lane_preserve.announce(lane.issue, saved.stash, RESTART_CAUSE)
+	}
+
+	return { kind: 'restarted', dispatch, stash: saved.stash }
+}
+
+// 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.
+async function stop_and_relaunch(lane: LaneInfo): Promise<RestartOutcome> {
+	if (lane_reap.reap_child(lane.issue).length === 0) return { kind: NOT_RUNNING_KIND }
+
+	return await relaunch(lane)
+}
+
+/** 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)
+	const lane = await lane_registry.find_open_lane(issue)
+
+	if (lane === undefined) return { kind: NO_LANE_KIND }
+	if (!lane_reap.is_child_running(issue)) return { kind: NOT_RUNNING_KIND }
+	const claim = await lane_dispatch.claim_marker(issue)
+
+	if (!claim.is_applied) return { kind: UNCLAIMED_KIND, reason: claim.reason }
+
+	return await stop_and_relaunch(lane)
+}
+
+function stash_sentence(stash: string | undefined): string {
+	if (stash === undefined) return 'The lane held no uncommitted work.'
+
+	return `Its uncommitted work was stashed — recover with \`pnpm josh stash:pop "${stash}"\`.`
+}
+
+// A dispatch that failed leaves the stopped child to `run:merge`: nothing re-appeared inside the
+// re-confirm window, so the parent collects it as it would any stopped child.
+function restarted_text(outcome: Restarted, issue: string): string {
+	const head = `Stopped the child for ${session_cite.issue(issue)}. ${stash_sentence(outcome.stash)}`
+	const dispatch = lane_dispatch.describe(outcome.dispatch, issue)
+
+	if (outcome.dispatch.kind === DISPATCHED_KIND) return `${head} ${dispatch}`
+
+	return `${head} The fresh dispatch failed, so \`run:merge\` will collect the stopped child: ${dispatch}`
+}
+
+function unsaved_text(outcome: Unsaved, issue: string): string {
+	return `The child for ${session_cite.issue(issue)} was stopped, but its uncommitted work could not be stashed (${outcome.reason}), so nothing was re-dispatched and the lane is left at ${outcome.directory}; \`run:merge\` will collect the stopped child.`
+}
+
+function refused_text(outcome: Refused, issue: string): string {
+	const cited = session_cite.issue(issue)
+
+	if (outcome.kind === NO_LANE_KIND) {
+		return `No lane is open for ${cited}, so there is no child to restart.`
+	}
+
+	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.`
+	}
+
+	return `No child is running in the lane for ${cited}, so nothing was stopped or re-dispatched — a child that has already ended is \`run:merge\`'s to collect.`
+}
+
+function describe(outcome: RestartOutcome, issue: string): string {
+	if (outcome.kind === 'unsaved') return unsaved_text(outcome, issue)
+
+	return outcome.kind === 'restarted'
+		? restarted_text(outcome, issue)
+		: refused_text(outcome, issue)
+}
+
+const lane_restart = { describe, restart }
+
+export type { RestartOutcome }
+export { lane_restart }