@joshuafolkken/kit 1.1240.0 → 1.1370.0

package/scripts/lane/lane-sampler.ts

@@ -0,0 +1,55 @@
+import { lane_ledger } from './lane-ledger'
+import { lane_load } from './lane-load'
+
+// The machine-load sampler: one `load` entry appended to the lane ledger, once or on a timer.
+//
+// **`start` is how a `backlogrun` samples itself.** `backlog:drive` starts it for as long as its loop
+// runs, so a period needs nobody to remember a second terminal — the sampler `josh lane:sample` offers
+// was started by hand, and a run nobody started it beside recorded no load at all. The timer lives in
+// the drive's own process and is unreferenced: it ends with the drive, never holds it open, and leaves
+// no process or pid file behind to stop.
+
+const SAMPLE_INTERVAL_MS = 60_000
+
+// Where the ledger is and what "now" is, overridable so a test reads a fixed ledger at a fixed instant.
+interface MeasureContext {
+	ledger_path?: string
+	now_ms?: number
+}
+
+async function take(context: MeasureContext = {}): Promise<void> {
+	const at = new Date(context.now_ms ?? Date.now()).toISOString()
+
+	await lane_ledger.record(await lane_load.sample(at), context.ledger_path)
+}
+
+// A timer tick has no caller to raise into, and a sample that could not be read must never end the run
+// it measures.
+async function take_quietly(context: MeasureContext): Promise<void> {
+	try {
+		await take(context)
+	} catch {
+		// Best-effort: an unread sample is a gap in the measurement, not a failure of the run.
+	}
+}
+
+/** Sample now and then every minute; the returned function stops it. */
+function start(context: MeasureContext = {}): () => void {
+	void take_quietly(context)
+	const timer = setInterval(() => {
+		void take_quietly(context)
+	}, SAMPLE_INTERVAL_MS).unref()
+
+	return () => {
+		clearInterval(timer)
+	}
+}
+
+const lane_sampler = {
+	SAMPLE_INTERVAL_MS,
+	start,
+	take,
+}
+
+export type { MeasureContext }
+export { lane_sampler }

package/scripts/lane/lane-seed.ts

@@ -1,13 +1,13 @@
-// Which seat a lane gets (joshuafolkken/kit#1490, joshuafolkken/kit#1494).
+// Which seat a lane gets.
 
 // **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).
+// **Nine seats, because the seat is the units digit of the offset `seed × 10 + lane`.** The seed,
+// multiplied by ten, carries the port band rather than the seat, 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.
 const LAST_LANE_SEAT = 9
 
 /**
@@ -20,8 +20,8 @@ const LAST_LANE_SEAT = 9
  * 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
+ * seat atomically and steps to the next when a concurrent `lane:open` claimed it first:
+ * 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> {

package/scripts/lane/lane-stage-stats.ts

@@ -0,0 +1,135 @@
+import { run_ship_stage } from '#scripts/run/ship/run-ship-stage'
+import { lane_ledger, type DispatchEntry, type LedgerEntry, type StageEntry } from './lane-ledger'
+import { lane_stats, type StatsWindow } from './lane-stats'
+
+// Where a lane's time goes: the ledger's `stage` and `dispatch` entries of one period reduced to one
+// row per stage — median, maximum and how many runs — printed by `josh lane:stats` under the lane-limit
+// row. The rows are in the order a lane passes them.
+//
+// **A stage nothing recorded prints `not measured`, never `0`.** A period that ran no second review
+// round has no `round-2` duration, which is not a round that took no time.
+//
+// **`implement` is derived, not recorded**: from a lane's dispatch to the start of the first ship stage
+// of the same issue that followed it. Nothing has to know, at the hand-off, when the child was
+// dispatched, and a ship resumed after a fix cannot record the implementation twice.
+//
+// **`ci-wait` is `followup`'s own lap, inside the `followup` stage** — a row of its own so the wait for
+// CI reads beside `review`, the round-one review it would overlap.
+
+const MS_PER_MINUTE = 60_000
+const DECIMALS = 1
+const NOT_MEASURED = 'not measured'
+const IMPLEMENT = 'implement'
+const COLUMNS = ['stage', 'median (min)', 'max (min)', 'runs'] as const
+const { STAGE } = run_ship_stage
+const STAGES = [
+	IMPLEMENT,
+	STAGE.PREFLIGHT,
+	STAGE.REVIEW,
+	STAGE.SYNC,
+	STAGE.GATE,
+	STAGE.COMMIT,
+	STAGE.ROUND_TWO,
+	STAGE.FOLLOWUP,
+	lane_ledger.CI_WAIT_STAGE,
+	STAGE.REPORT,
+] as const
+
+interface Measured {
+	implement: ReadonlyArray<number>
+	stages: ReadonlyArray<StageEntry>
+}
+
+function is_stage(entry: LedgerEntry): entry is StageEntry {
+	return entry.kind === lane_ledger.KIND.STAGE
+}
+
+function is_dispatch(entry: LedgerEntry): entry is DispatchEntry {
+	return entry.kind === lane_ledger.KIND.DISPATCH
+}
+
+function is_number(value: number | undefined): value is number {
+	return value !== undefined
+}
+
+function started_ms(stage: StageEntry): number {
+	return Date.parse(stage.at) - stage.elapsed_ms
+}
+
+// When the same issue was dispatched again, or never: a child that died before its ship must not have
+// its implementation stretched to the ship of the child that replaced it.
+function next_dispatch_ms(sorted: ReadonlyArray<DispatchEntry>, index: number): number {
+	const next = sorted.slice(index + 1).find((entry) => entry.issue === sorted[index]?.issue)
+
+	return next === undefined ? Infinity : Date.parse(next.at)
+}
+
+function implement_ms(
+	dispatch: DispatchEntry,
+	until_ms: number,
+	stages: ReadonlyArray<StageEntry>,
+): number | undefined {
+	const from_ms = Date.parse(dispatch.at)
+	const starts = stages
+		.filter((stage) => stage.issue === dispatch.issue)
+		.map((stage) => started_ms(stage))
+		.filter((start) => start >= from_ms && start < until_ms)
+
+	return starts.length === 0 ? undefined : Math.min(...starts) - from_ms
+}
+
+function implement_durations(
+	dispatches: ReadonlyArray<DispatchEntry>,
+	stages: ReadonlyArray<StageEntry>,
+): Array<number> {
+	const sorted = dispatches.toSorted((left, right) => Date.parse(left.at) - Date.parse(right.at))
+
+	return sorted
+		.map((dispatch, index) => implement_ms(dispatch, next_dispatch_ms(sorted, index), stages))
+		.filter(is_number)
+}
+
+function durations_of(stage: string, measured: Measured): ReadonlyArray<number> {
+	if (stage === IMPLEMENT) return measured.implement
+
+	return measured.stages.filter((entry) => entry.stage === stage).map((entry) => entry.elapsed_ms)
+}
+
+function cell(milliseconds: number | undefined): string {
+	return milliseconds === undefined
+		? NOT_MEASURED
+		: (milliseconds / MS_PER_MINUTE).toFixed(DECIMALS)
+}
+
+function stage_row(stage: string, measured: Measured): string {
+	const durations = durations_of(stage, measured)
+
+	return lane_stats.to_row([
+		stage,
+		cell(lane_stats.median(durations)),
+		cell(lane_stats.peak(durations)),
+		String(durations.length),
+	])
+}
+
+// The period's table: `entries` is the whole ledger, filtered here to `window`.
+function table(entries: ReadonlyArray<LedgerEntry>, window: StatsWindow): string {
+	const period = lane_stats.in_window(entries, window)
+	const stages = period.filter(is_stage)
+	const measured = { implement: implement_durations(period.filter(is_dispatch), stages), stages }
+
+	return [
+		lane_stats.to_row(COLUMNS),
+		lane_stats.to_row(COLUMNS.map(() => '---')),
+		...STAGES.map((stage) => stage_row(stage, measured)),
+	].join('\n')
+}
+
+const lane_stage_stats = {
+	IMPLEMENT,
+	NOT_MEASURED,
+	STAGES,
+	table,
+}
+
+export { lane_stage_stats }

package/scripts/lane/lane-start-point.ts

@@ -1,15 +1,14 @@
 import { git_command } from '#scripts/git/git-command'
 import { git_remote_branch } from '#scripts/git/git-remote-branch'
 
-// Where a lane is cut from (joshuafolkken/kit#1535).
+// Where a lane is cut from.
 //
 // **The bare default-branch name is the wrong start point, because git resolves it to the *local*
 // `refs/heads/<default>` — a ref nothing in this workflow ever advances.** Merges happen on GitHub
 // through `pnpm josh followup`, and this repository's main work tree does not have the
 // default branch checked out, so there is no fast-forward for it to receive. It falls one commit
 // further behind on every merge, and a lane opened from it starts without the work that was just
-// merged. Measured on 2026-09-07: `refs/heads/main` was `e3a68c04` while `refs/remotes/origin/main`
-// was `78f746f9`.
+// merged.
 //
 // **The remote-tracking ref is the one that is current**, because a fetch updates it without anyone
 // checking anything out — which is exactly the property the local branch lacks. It is named in full
@@ -20,9 +19,9 @@ const REFS_REMOTES_ORIGIN_PREFIX = 'refs/remotes/origin/'
 
 // A fetch *failure* is reported and stepped over rather than raised. `lane:open` has to keep working
 // with no network at all — offline, and on a clone with no `origin` — and what it degrades to is
-// whatever `origin/<default>` already holds, which is still never *behind* the local branch. Note
-// what this does not cover: `fetch_branch` runs through `git_spawn.read`, which sets no
-// timeout, so a connection that hangs rather than failing blocks here instead of degrading.
+// whatever `origin/<default>` already holds, which is still never *behind* the local branch. A
+// connection that hangs rather than failing degrades the same way: `fetch_branch` runs through
+// `git_spawn.read_remote`, whose budget ends the wait as a failure.
 async function refresh_default_branch(default_branch: string): Promise<void> {
 	try {
 		await git_command.fetch_branch(default_branch)
@@ -65,7 +64,7 @@ async function resolve(): Promise<string> {
 	return start_point
 }
 
-// **A branch that already exists is attached to, never cut afresh** (joshuafolkken/kit#1627). Its
+// **A branch that already exists is attached to, never cut afresh**. Its
 // commits are a child's finished work: `epicrun` leaves a lane's branch behind whenever a child is
 // parked after pushing, and `lane:close` deletes the local branch while the remote one and the pull
 // request stay. Cutting a new `<N>-lane` from the default branch there orphans both — and it did so
@@ -130,8 +129,7 @@ async function present_reference(branch_name: string): Promise<string> {
 
 // `absent` is the one answer that refuses the ref: the branch is gone from origin, so a ref still
 // pointing at it is stale and the lane is cut from the default branch as any new one is. Why origin
-// itself is asked rather than the remote-tracking ref is `git_remote_branch`'s own comment
-// (joshuafolkken/kit#1641 moved the asking there, so `pnpm josh release` could reuse it).
+// itself is asked rather than the remote-tracking ref is `git_remote_branch`'s own comment.
 async function remote_reference_for(branch_name: string): Promise<string | undefined> {
 	const answer = await git_remote_branch.ask(branch_name)
 
@@ -148,8 +146,7 @@ async function remote_reference_for(branch_name: string): Promise<string | undef
  *
  * `undefined` means **attach**: the branch is already here, so the work tree is put on it and no
  * branch is created. Every other answer is a commit-ish a new branch is cut from — the remote-tracking
- * ref of the lane branch when only the remote has it, and the default branch's when neither does,
- * which is the behavior every lane had before joshuafolkken/kit#1627.
+ * ref of the lane branch when only the remote has it, and the default branch's when neither does.
  *
  * **Nothing here deletes a branch to simplify the call.** That is what would lose the commits this
  * function exists to keep.

package/scripts/lane/lane-stats.ts

@@ -1,6 +1,8 @@
+import { machine_capacity } from '#scripts/gate/machine-capacity'
 import type { GateEntry, LedgerEntry, LoadEntry } from './lane-ledger'
+import { lane_sampler } from './lane-sampler'
 
-// The lane-limit measurement's one table row (joshuafolkken/kit#3355): the ledger entries of one period
+// The lane-limit measurement's one table row: the ledger entries of one period
 // reduced to throughput, gate duration and machine load, in the column order
 // `docs/maintainers/lane-limit-measurement.md` documents, so the row pastes into #3347's table as is.
 //
@@ -15,6 +17,9 @@ import type { GateEntry, LedgerEntry, LoadEntry } from './lane-ledger'
 //
 // **The means take working samples only** for the same reason: the sampler runs through the nights,
 // and their idle samples would read four busy lanes as about one. Peaks and minima take every sample.
+//
+// **Swap is a rate, not a level.** A sample carries `machine_capacity`'s counter — every page swapped
+// since boot — so the swap columns are what was swapped between consecutive samples, per hour.
 
 const MS_PER_MINUTE = 60_000
 const MS_PER_HOUR = 3_600_000
@@ -23,6 +28,8 @@ const ACTIVE_GAP_MS = MS_PER_HOUR
 const MS_PER_DAY = 86_400_000
 const MB_PER_GB = 1024
 const HALF = 2
+// Half the sampler's interval: two samples closer than this are not one interval apart.
+const MIN_RATE_GAP_MS = lane_sampler.SAMPLE_INTERVAL_MS / HALF
 const DECIMALS = 1
 const MISSING = '—'
 const CELL_SEPARATOR = ' | '
@@ -37,8 +44,8 @@ const COLUMNS = [
 	'gate max (min)',
 	'load peak',
 	'load mean',
-	'swap peak (GB)',
-	'swap mean (GB)',
+	'swapped peak (GB/h)',
+	'swapped mean (GB/h)',
 	'free memory min (GB)',
 	'free memory mean (GB)',
 	'load samples',
@@ -107,6 +114,22 @@ function is_working(sample: LoadEntry): sample is WorkingEntry {
 	return (sample.lanes ?? 0) > 0
 }
 
+interface SamplePair {
+	sample: LoadEntry
+	next: LoadEntry
+}
+
+// Each sample beside the one that followed it, in time order.
+function sample_pairs(samples: ReadonlyArray<LoadEntry>): Array<SamplePair> {
+	const sorted = samples.toSorted((left, right) => Date.parse(left.at) - Date.parse(right.at))
+
+	return sorted.slice(1).map((next, index) => ({ sample: sorted[index] ?? next, next }))
+}
+
+function elapsed_ms({ sample, next }: SamplePair): number {
+	return Date.parse(next.at) - Date.parse(sample.at)
+}
+
 function sum_hours(gaps: ReadonlyArray<number>): number | undefined {
 	const active = gaps.filter((gap) => gap <= ACTIVE_GAP_MS).reduce((sum, gap) => sum + gap, 0)
 
@@ -117,7 +140,7 @@ function sum_hours(gaps: ReadonlyArray<number>): number | undefined {
 // and gates) no longer than `ACTIVE_GAP_MS`.
 function gap_hours(entries: ReadonlyArray<LedgerEntry>): number | undefined {
 	const instants = entries
-		.filter((entry) => !is_load(entry))
+		.filter((entry) => entry.kind === 'merge' || is_gate(entry))
 		.map((entry) => Date.parse(entry.at))
 		.toSorted((left, right) => left - right)
 
@@ -129,16 +152,27 @@ function gap_hours(entries: ReadonlyArray<LedgerEntry>): number | undefined {
 // The time from each working sample to the next sample. The cap still applies, so a sampler stopped
 // mid-run does not count its silence as work.
 function sampled_hours(samples: ReadonlyArray<LoadEntry>): number | undefined {
-	const sorted = samples.toSorted((left, right) => Date.parse(left.at) - Date.parse(right.at))
-	const gaps = sorted
-		.slice(1)
-		.map((next, index) => ({ sample: sorted[index] ?? next, next }))
+	const gaps = sample_pairs(samples)
 		.filter(({ sample }) => is_working(sample))
-		.map(({ sample, next }) => Date.parse(next.at) - Date.parse(sample.at))
+		.map((pair) => elapsed_ms(pair))
 
 	return sum_hours(gaps)
 }
 
+// The GB swapped per hour from one sample to the next. `swapped_mb` is a counter, so only a difference
+// says anything; a gap past `ACTIVE_GAP_MS` is a stopped sampler, whose silence is no rate. A gap under
+// `MIN_RATE_GAP_MS` is no rate either: a drive restarted seconds after its last sample, or a second
+// sampler beside it, would stretch a few seconds' burst to an hour and own the peak.
+function swap_rate(pair: SamplePair): number | undefined {
+	const swapped = machine_capacity.swapped_between(pair.sample.swapped_mb, pair.next.swapped_mb)
+	const elapsed = elapsed_ms(pair)
+	const is_one_interval = elapsed >= MIN_RATE_GAP_MS && elapsed <= ACTIVE_GAP_MS
+
+	if (swapped === undefined || !is_one_interval) return undefined
+
+	return swapped / MB_PER_GB / (elapsed / MS_PER_HOUR)
+}
+
 // The hours work was under way; `undefined` when nothing leaves any active time.
 function active_hours(entries: ReadonlyArray<LedgerEntry>): number | undefined {
 	const samples = entries.filter(is_load)
@@ -172,18 +206,26 @@ function gate_cells(entries: ReadonlyArray<LedgerEntry>): Array<string> {
 	return [cell(median(minutes)), cell(peak(minutes))]
 }
 
+function swap_cells(samples: ReadonlyArray<LoadEntry>): Array<string> {
+	const pairs = sample_pairs(samples)
+	const rates = pairs.map((pair) => swap_rate(pair)).filter(is_number)
+	const working_rates = pairs
+		.filter(({ sample }) => is_working(sample))
+		.map((pair) => swap_rate(pair))
+		.filter(is_number)
+
+	return [cell(peak(rates)), cell(mean(working_rates))]
+}
+
 function load_cells(samples: ReadonlyArray<LoadEntry>): Array<string> {
 	const working = samples.filter(is_working)
-	const swap = samples.map((sample) => sample.swap_mb).filter(is_number)
-	const working_swap = working.map((sample) => sample.swap_mb).filter(is_number)
-	const free = samples.map((sample) => sample.free_mb)
-	const working_free = working.map((sample) => sample.free_mb)
+	const free = samples.map((sample) => sample.available_mb).filter(is_number)
+	const working_free = working.map((sample) => sample.available_mb).filter(is_number)
 
 	return [
 		cell(peak(samples.map((sample) => sample.load))),
 		cell(mean(working.map((sample) => sample.load))),
-		cell(gigabytes(peak(swap))),
-		cell(gigabytes(mean(working_swap))),
+		...swap_cells(samples),
 		cell(gigabytes(lowest(free))),
 		cell(gigabytes(mean(working_free))),
 		String(samples.length),
@@ -215,8 +257,11 @@ const lane_stats = {
 	COLUMNS,
 	MISSING,
 	header,
+	in_window,
 	median,
+	peak,
 	row,
+	to_row,
 	window_of,
 }
 

package/scripts/lane/lane-stray.ts

@@ -6,7 +6,7 @@ import { lane_open } from './lane-open'
 import { lane_paths } from './lane-paths'
 import { lane_registry } from './lane-registry'
 
-// What the lanes root holds that no registered work tree accounts for (joshuafolkken/kit#3370).
+// What the lanes root holds that no registered work tree accounts for.
 //
 // **Every other sweep starts from `git worktree list`**, so a directory whose registration is gone —
 // a lane whose `rmSync` stopped half-way, one whose `.git` points at a registration git pruned, an

package/scripts/lane/lane-vacant.ts

@@ -3,7 +3,7 @@ import { run_hold } from '#scripts/run/hold/run-hold'
 import { lane_await } from './lane-await'
 import type { LaneInfo } from './lane-registry'
 
-// Whether an open lane holds nothing worth keeping (joshuafolkken/kit#3289): no commit on its branch
+// Whether an open lane holds nothing worth keeping: no commit on its branch
 // beyond the default branch, a clean work tree, and no child or ship supervisor alive for its issue. A
 // `backlogrun` cut between `lane:open` and `lane:dispatch` leaves exactly such a lane, and `lane:open`
 // refuses it as `already-open` — so the next launch of that issue failed on a lane with nothing in it.

package/scripts/lane/openai-lane-supervisor-decision.ts

@@ -1,4 +1,5 @@
 import { stamp_file } from '#scripts/josh/stamp-file'
+import { json_value } from '#scripts/lib/json-value'
 import { z } from 'zod'
 
 const DECISION_PREFIX = 'josh-openai-lane-supervisor-decision-'
@@ -16,14 +17,9 @@ function target(lane_directory: string, nonce: string): string {
 }
 
 function read(lane_directory: string, nonce: string): Decision | undefined {
-	try {
-		const raw = stamp_file.read_stamp_text(target(lane_directory, nonce)) ?? ''
-		const value: unknown = JSON.parse(raw)
+	const raw = stamp_file.read_stamp_text(target(lane_directory, nonce)) ?? ''
 
-		return schema.parse(value)
-	} catch {
-		return undefined
-	}
+	return json_value.parse_with(raw, schema)
 }
 
 function decide(lane_directory: string, nonce: string, decision: Decision['decision']): boolean {

package/scripts/lane/openai-lane-supervisor-owner.ts

@@ -3,11 +3,12 @@ import { linkSync, statSync, unlinkSync } from 'node:fs'
 import { process_identity } from '#scripts/josh/process-identity'
 import { process_owner_schema } from '#scripts/josh/process-owner'
 import { stamp_file } from '#scripts/josh/stamp-file'
+import { json_value } from '#scripts/lib/json-value'
 import { z } from 'zod'
 import { openai_lane_supervisor_decision } from './openai-lane-supervisor-decision'
 
 // The supervisor's owner and state stamps — who holds a lane, and which child it last launched —
-// split out of `openai-lane-supervisor.ts` when it reached its line limit (joshuafolkken/kit#3264).
+// split out of `openai-lane-supervisor.ts` when it reached its line limit.
 // `openai_lane_supervisor` re-exports each public one under the name it always had, so the move
 // changed no call site and no suite that spies on `openai_lane_supervisor`.
 
@@ -41,14 +42,7 @@ function state_path(lane_directory: string): string {
 }
 
 function parsed_stamp<T>(target: string, schema: z.ZodType<T>): T | undefined {
-	try {
-		const value: unknown = JSON.parse(stamp_file.read_stamp_text(target) ?? '')
-		const parsed = schema.safeParse(value)
-
-		return parsed.success ? parsed.data : undefined
-	} catch {
-		return undefined
-	}
+	return json_value.parse_with(stamp_file.read_stamp_text(target) ?? '', schema)
 }
 
 function read(lane_directory: string): SupervisorOwner | undefined {

package/scripts/lane/openai-review-broker.ts

@@ -7,6 +7,7 @@ import { agent_role_profile } from '#scripts/agent/agent-role-profile'
 import { git_common_directory } from '#scripts/git/git-common-directory'
 import { stamp_file } from '#scripts/josh/stamp-file'
 import { error_text } from '#scripts/lib/error-message'
+import { json_value } from '#scripts/lib/json-value'
 import { detached_launch } from '#scripts/run/detached-launch'
 import { run_ship_review } from '#scripts/run/ship/run-ship-review'
 import { z } from 'zod'
@@ -60,10 +61,7 @@ function response_path(directory: string, issue: string): string | undefined {
 
 function read_record<T>(target: string, schema: z.ZodType<T>): T | undefined {
 	try {
-		const content: unknown = JSON.parse(readFileSync(target, 'utf8'))
-		const parsed = schema.safeParse(content)
-
-		return parsed.success ? parsed.data : undefined
+		return json_value.parse_with(readFileSync(target, 'utf8'), schema)
 	} catch {
 		return undefined
 	}

package/scripts/lib/ancestor-directories.ts

@@ -1,6 +1,6 @@
 import path from 'node:path'
 
-// One parent-directory walk, in one place (joshuafolkken/kit#3260). Five modules had each written
+// One parent-directory walk, in one place. Five modules had each written
 // their own — the josh package-root lookup, the gate's project root, the effective-upstream version
 // read, the local-bin shim search and the progress-interval read — and they had drifted to three
 // different stop conditions. The walk stops at the filesystem root (where `dirname` answers itself)

package/scripts/lib/bounded-pool.ts

@@ -5,7 +5,7 @@
 // and `epic-bundle-referenced.ts` each read one issue per reference and must not turn a rate limit
 // into a wrong answer. The reads were written as waves — slice, `Promise.all`, next slice — which
 // idles the whole batch behind its slowest member, so the three were neither the same code nor the
-// same behavior (joshuafolkken/kit#1144).
+// same behavior.
 //
 // A worker pool instead: `limit` consumers pull from one queue, so a slot is refilled the moment its
 // task ends rather than when its neighbors do.
@@ -32,7 +32,7 @@ interface Pool<Item, Result> {
 // so the clamp passes it straight through and `Array.from({ length: NaN })` builds no consumer at all
 // — an empty result for a non-empty input, which is precisely what the paragraph above promises
 // cannot happen. A caller reading that promise is entitled not to validate first, so it is closed
-// here (joshuafolkken/kit#1144). A fractional limit is floored for the same reason: `Array.from`
+// here. A fractional limit is floored for the same reason: `Array.from`
 // truncates it silently, and a width that is not the number asked for should be a decision rather
 // than a side effect.
 function pool_width(limit: number, total: number): number {

package/scripts/lib/buffered-process.ts

@@ -7,8 +7,7 @@ import { SUITE_TIMEOUT_MS } from './timeouts'
 // need the same three things: the output buffered until the child finishes (concurrent writers
 // otherwise interleave into an unreadable transcript), a non-zero exit reported rather than thrown
 // (so one failing check does not abort its siblings), and a bound on how long a child may hang.
-// They had the same code twice, which is how a fix to one of them missed the other
-// (joshuafolkken/kit#914).
+// They had the same code twice, which is how a fix to one of them missed the other.
 
 const PNPM = 'pnpm'
 const FORCE_COLOR = '1'
@@ -21,13 +20,12 @@ interface BufferedProcessResult {
 	exit_code: number | undefined
 	// How long the child ran, in milliseconds. Measured here rather than at each call site because
 	// this function owns the child's lifetime — a caller timing it from outside would have to repeat
-	// the same two readings, and every fan-out caller would repeat them once per branch
-	// (joshuafolkken/kit#1248).
+	// the same two readings, and every fan-out caller would repeat them once per branch.
 	elapsed_ms: number
 }
 
-// The two things a caller outside the fan-out needs to vary, and the only two
-// (joshuafolkken/kit#1554). `lane:open` runs its install in the work tree it just created rather
+// The two things a caller outside the fan-out needs to vary, and the only two.
+// `lane:open` runs its install in the work tree it just created rather
 // than in the directory `josh` was typed in, and bounds it well under the fan-out's half hour
 // because an install that never answers has to end the command rather than hold a parallel run
 // open. Everything else — the buffering, the non-throwing exit, and the color policy that respects

package/scripts/lib/cli-flags.ts

@@ -1,9 +1,19 @@
 import { parseArgs, type ParseArgsConfig, type ParseArgsOptionsConfig } from 'node:util'
 
 // Argument reading for the commands under `scripts/`.
-//
+
+const HELP_FLAGS: ReadonlySet<string> = new Set(['--help', '-h'])
+
+// The usage line `refuse_unknown_flags` ends with, for a command that prints it on its own help
+// request (`josh release --help`).
+function usage_line(known_flags: ReadonlyArray<string>, command: string): string {
+	if (known_flags.length === 0) return `Usage: josh ${command}`
+
+	return `Usage: josh ${command} [${known_flags.join('] [')}]`
+}
+
 // Reject anything not on the list rather than ignoring it: a misspelled `--dryrun` that fell through
-// would run the real write path. `josh propagate` and `josh adopt` both write into working trees, so
+// would run the real write path. `josh propagate`, `josh adopt` and `josh release` all write, so
 // the refusal is single-sourced here rather than described once per command (`CLAUDE.md` → "No
 // clones").
 function refuse_unknown_flags(
@@ -13,15 +23,36 @@ function refuse_unknown_flags(
 ): string | undefined {
 	const unknown = argv.filter((argument) => !known_flags.includes(argument))
 	if (unknown.length === 0) return undefined
-	const usage = `Usage: josh ${command} [${known_flags.join('] [')}]`
 
-	return `Unknown argument(s): ${unknown.join(' ')}\n${usage}`
+	return `Unknown argument(s): ${unknown.join(' ')}\n${usage_line(known_flags, command)}`
+}
+
+// The argument gate of a command that publishes (`josh release`, `josh release:github`): a help
+// request prints the usage and exits 0, an unknown argument is refused with exit 1, both before any side effect. `undefined` means the
+// arguments are all known and the command may run.
+function answer_help_or_unknown(
+	argv: ReadonlyArray<string>,
+	known_flags: ReadonlyArray<string>,
+	command: string,
+): number | undefined {
+	if (argv.some((argument) => HELP_FLAGS.has(argument))) {
+		console.info(usage_line(known_flags, command))
+
+		return 0
+	}
+
+	const refusal = refuse_unknown_flags(argv, known_flags, command)
+	if (refusal === undefined) return undefined
+
+	console.error(refusal)
+
+	return 1
 }
 
 // `parseArgs`, answering `undefined` where it would throw — an unknown flag, a missing option value,
 // or a positional the config does not allow. Each caller turns that into its usage line and a failure
 // exit rather than a stack trace, on commands whose output a workflow reads; eleven of them had begun
-// to carry a copy of the same try/catch each (joshuafolkken/kit#2902), and this is the one copy.
+// to carry a copy of the same try/catch each, and this is the one copy.
 function parse_or_undefined<T extends ParseArgsConfig>(
 	config: T,
 ): ReturnType<typeof parseArgs<T>> | undefined {
@@ -34,7 +65,7 @@ function parse_or_undefined<T extends ParseArgsConfig>(
 
 // The two shapes every command reads `argv` in: flags alone, or flags beside positionals. Both are
 // strict, so an unknown flag is `undefined` rather than a silently ignored typo; the commands had each
-// carried a one-line wrapper spelling these out (joshuafolkken/kit#3072).
+// carried a one-line wrapper spelling these out.
 type FlagsOnly<T extends ParseArgsOptionsConfig> = ReturnType<
 	typeof parseArgs<{ args: Array<string>; options: T }>
 >
@@ -123,7 +154,9 @@ function attach_values(
 
 const cli_flags = {
 	attach_values,
+	usage_line,
 	refuse_unknown_flags,
+	answer_help_or_unknown,
 	parse_or_undefined,
 	values_of,
 	arguments_of,