@joshuafolkken/kit 1.872.0

package/scripts/run/run-ship-stage.ts

@@ -0,0 +1,150 @@
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { z } from 'zod'
+
+// `josh ship`'s durable stage record, and the decision of which stage a resumed ship may pass over
+// (joshuafolkken/kit#2426). The composite used to be a straight line with no memory: a ship that died
+// after its push re-ran the gate, and nothing checked whether the commit, the push or the merge had
+// already happened.
+//
+// **The record is a hint; the repository's actual state is the authority.** A record can be lost — a
+// temp directory wiped — or outlived by the tree it describes, when new work was committed after it
+// was written. So every skip below is decided from the observed state first, and a recorded stage is
+// honored only where that state still corroborates it: a lost record re-derives the same answer from
+// the state, and a stale one is overruled by it. Neither can produce a second commit, push or merge.
+//
+// **The gate is never skipped on the record's word.** It is passed over only once its output — a
+// commit — exists; otherwise it runs, and `josh gate`'s own tree-keyed green record is what makes a
+// re-run on an unchanged tree a reuse rather than a second execution. No quality gate is folded away.
+
+const STAGE = {
+	REVIEW: 'review',
+	GATE: 'gate',
+	COMMIT: 'commit',
+	ROUND_TWO: 'round-2',
+	FOLLOWUP: 'followup',
+	REPORT: 'report',
+} as const
+
+type Stage = (typeof STAGE)[keyof typeof STAGE]
+
+// Where one stage is on the event stream: started, succeeded, failed, or passed over as already done.
+const PHASE = {
+	START: 'start',
+	DONE: 'done',
+	FAILED: 'failed',
+	SKIPPED: 'skipped',
+} as const
+
+type Phase = (typeof PHASE)[keyof typeof PHASE]
+
+interface ShipState {
+	is_committed: boolean
+	is_pushed: boolean
+	is_merged: boolean
+}
+
+const RECORD_PREFIX = 'josh-ship-stages-'
+const RECORD_SEPARATOR = '-'
+const SKIP_COMMIT_FLAG = '--skip-commit'
+const SKIP_PUSH_FLAG = '--skip-push'
+
+const record_schema = z.object({ done: z.array(z.string()) })
+
+// Keyed on the repository and the issue: every lane of one repository shares the common git directory,
+// and two issues shipping from two lanes keep two records.
+function record_path(repository: string, issue: string): string {
+	return stamp_file.stamp_path(`${RECORD_PREFIX}${issue}${RECORD_SEPARATOR}`, repository)
+}
+
+function parse_done(raw: string): ReadonlySet<string> {
+	try {
+		return new Set(record_schema.parse(JSON.parse(raw)).done)
+	} catch {
+		return new Set()
+	}
+}
+
+// The stages the record says completed. An absent, planted or malformed record reads as none — the
+// state decides from there, so "no record" is always the safe answer.
+function read_done(target: string): ReadonlySet<string> {
+	const raw = stamp_file.read_stamp_text(target)
+
+	return raw === undefined ? new Set() : parse_done(raw)
+}
+
+function mark_done(target: string, stage: Stage): void {
+	const done = new Set([...read_done(target), stage])
+
+	stamp_file.replace_stamp(target, { done: [...done] })
+}
+
+// Removed once the report stage completes, so a later ship of the same issue starts from the gate.
+function clear(target: string): void {
+	stamp_file.remove_stamp(target)
+}
+
+// Committed and on origin: the only state in which the commit stage has nothing left but the pull
+// request, which `git -y` already finds rather than duplicates.
+function is_shipped(state: ShipState): boolean {
+	return state.is_committed && state.is_pushed
+}
+
+const DONE_BY: Record<Stage, (done: ReadonlySet<string>, state: ShipState) => boolean> = {
+	// The `--review` round (joshuafolkken/kit#2427) precedes the commit, so a commit is its output as it
+	// is the gate's. A record alone is not honored: before a commit the tree may have been edited since
+	// the recorded round, and only a commit pins the tree that round read.
+	[STAGE.REVIEW]: (_done, state) => state.is_merged || state.is_committed,
+	[STAGE.GATE]: (_done, state) => state.is_merged || state.is_committed,
+	[STAGE.COMMIT]: (done, state) => state.is_merged || (done.has(STAGE.COMMIT) && is_shipped(state)),
+	// The round-2 pass (joshuafolkken/kit#2489) reads the pushed fix delta, so its record is honored only
+	// while that push still stands — new work pushed on top reruns it.
+	[STAGE.ROUND_TWO]: (done, state) =>
+		state.is_merged || (done.has(STAGE.ROUND_TWO) && is_shipped(state)),
+	// A recorded followup still needs the shipped state: a record left by a merged ship whose report
+	// failed must not pass over the followup of new, not-yet-pushed work on the same issue.
+	[STAGE.FOLLOWUP]: (done, state) =>
+		state.is_merged || (done.has(STAGE.FOLLOWUP) && is_shipped(state)),
+	[STAGE.REPORT]: (done) => done.has(STAGE.REPORT),
+}
+
+// A supplied PR body is work only the commit stage delivers (joshuafolkken/kit#2446): a rerun carrying
+// the live-execution evidence a refused `followup` asked for reruns `git -y`, whose skip flags leave the
+// commit and push alone while the body reaches the already-open pull request.
+function is_done(
+	stage: Stage,
+	done: ReadonlySet<string>,
+	state: ShipState,
+	has_body = false,
+): boolean {
+	if (has_body && stage === STAGE.COMMIT && !state.is_merged) return false
+
+	return DONE_BY[stage](done, state)
+}
+
+// The `git -y` flags that keep a resumed commit stage from repeating what already happened: an
+// existing commit is not made again, and a commit already on origin is not pushed again. A push is
+// skipped only on top of a skipped commit — new work committed now must still be pushed.
+function commit_flags(state: ShipState): ReadonlyArray<string> {
+	if (!state.is_committed) return []
+
+	return state.is_pushed ? [SKIP_COMMIT_FLAG, SKIP_PUSH_FLAG] : [SKIP_COMMIT_FLAG]
+}
+
+function event_text(issue: string, stage: Stage, phase: Phase): string {
+	return `#${issue} ${stage} ${phase}`
+}
+
+const run_ship_stage = {
+	PHASE,
+	STAGE,
+	clear,
+	commit_flags,
+	event_text,
+	is_done,
+	mark_done,
+	read_done,
+	record_path,
+}
+
+export type { Phase, ShipState, Stage }
+export { run_ship_stage }

package/scripts/run/run-ship.ts

@@ -0,0 +1,78 @@
+// `josh ship "<title> #<N>"` — the one call that ships a finished change (joshuafolkken/kit#2398). It
+// folds the fixed commit-to-report region a run spent a dozen round trips on — the gate, the
+// commit/push/PR (`git -y`), the CI-wait merge (`followup`) and the report bookkeeping (`run:tail`) —
+// into one composite, extending the post-merge fold of `run:tail` (joshuafolkken/kit#2372) into the
+// body of the region. The region is fixed procedure; the one decision it carried — disposing of a
+// review finding — stays in front of this command, so nothing a reader had to judge is folded away.
+//
+// **This module is the pure half**, kept apart from the chaining CLI the way `run-tail.ts` is. Unlike
+// `run:tail`, ship stops at the first failed step: a red gate must never reach the commit, so the
+// composite ends at the failure, and the report names the step that failed so the run reads only it.
+
+const REVIEW_HEADER = '=== review ==='
+const GATE_HEADER = '=== gate ==='
+const COMMIT_HEADER = '=== commit/push/PR ==='
+const ROUND_TWO_HEADER = '=== round-2 review ==='
+const FOLLOWUP_HEADER = '=== followup ==='
+const REPORT_HEADER = '=== report ==='
+const SECTION_SEPARATOR = '\n\n'
+const STOPPED_PREFIX = 'stopped at: '
+// The body of a stage a resumed ship passed over (joshuafolkken/kit#2426) — a success, so the report
+// still shows every stage under its header and the reader sees which ones this call did not repeat.
+const SKIPPED_BODY = 'skipped — already done'
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+
+interface ShipSection {
+	header: string
+	body: string
+	code: number
+}
+
+function section_report(section: ShipSection): string {
+	return `${section.header}\n${section.body}`
+}
+
+// The step that stopped the ship, or `undefined` when every executed step was green. Because the
+// composite breaks at the first failure, this is the last section whenever one exists.
+function failed_section(sections: ReadonlyArray<ShipSection>): ShipSection | undefined {
+	return sections.find((section) => section.code !== SUCCESS_EXIT_CODE)
+}
+
+// The executed steps under their headers, closed with the name of the step that stopped the run so the
+// reader sees which one to fix without counting sections.
+function format_report(sections: ReadonlyArray<ShipSection>): string {
+	const body = sections.map((section) => section_report(section)).join(SECTION_SEPARATOR)
+	const failed = failed_section(sections)
+
+	if (failed === undefined) return body
+
+	return `${body}${SECTION_SEPARATOR}${STOPPED_PREFIX}${failed.header}`
+}
+
+// Non-zero when any executed step failed — the composite only ever collects a failed step as its last,
+// so this reads the same clean/red verdict as the loop that stopped there.
+function exit_code(sections: ReadonlyArray<ShipSection>): number {
+	const is_clean = sections.every((section) => section.code === SUCCESS_EXIT_CODE)
+
+	return is_clean ? SUCCESS_EXIT_CODE : FAILURE_EXIT_CODE
+}
+
+const run_ship = {
+	COMMIT_HEADER,
+	FOLLOWUP_HEADER,
+	GATE_HEADER,
+	REPORT_HEADER,
+	REVIEW_HEADER,
+	ROUND_TWO_HEADER,
+	SKIPPED_BODY,
+	STOPPED_PREFIX,
+	SUCCESS_EXIT_CODE,
+	exit_code,
+	failed_section,
+	format_report,
+}
+
+export type { ShipSection }
+export { run_ship }

package/scripts/run/run-status-cli.ts

@@ -0,0 +1,175 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { parseArgs } from 'node:util'
+import { cost_cli, type CostVerdict } from '#scripts/cost-runtime/cost-cli'
+import { issue_state_cli, type StateRead } from '#scripts/issue/issue-state-cli'
+import { run_carry, type CarryRead } from './run-carry'
+import { run_status, type StatusParts } from './run-status'
+
+// `josh run:status <N>` — one call for the read-only status a run glances at (joshuafolkken/kit#2165):
+// the issue's state and labels (`issue:state`), the session's hand-off verdict (`cost --cut`), and the
+// invocation's carry counters (`run:carry`). Each is reused rather than reproduced, and the two async
+// reads run concurrently, so three round trips become one.
+//
+// **Nothing here writes.** The claim `run:hold` makes and the clock mark `run:progress` records are
+// deliberately out: this command answers "where does this run stand", and a status read that mutated
+// the thing it read is the bug the read-only pin (`run-status-cli.test.ts`) exists to catch. The merge
+// event keeps its own composite (`run:merge`), which is where the same three facts are read to *act*.
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const ARGV_OFFSET = 2
+const ISSUE_NUMBER_PATTERN = /^[1-9]\d*$/u
+const USAGE = 'Usage: josh run:status <issue-number> [--repo <owner/repo>]'
+const CARRY_NONE_NOTE = 'no run recorded here'
+const CARRY_UNREADABLE_NOTE = '(run record not bundled: unreadable)'
+const CARRY_SUMMARY_NONE = 'none'
+const CARRY_SUMMARY_EXPIRED = 'expired'
+const CARRY_SUMMARY_UNREADABLE = 'unreadable'
+const MERGED_SUFFIX = ' merged'
+
+const OPTIONS = { repo: { type: 'string' } } as const
+
+interface StatusRequest {
+	issue_number: string
+	repo?: string
+}
+
+interface StatusReads {
+	state: StateRead
+	carry: CarryRead
+	cost: CostVerdict
+}
+
+interface ParsedArguments {
+	positionals: ReadonlyArray<string>
+	values: { repo?: string }
+}
+
+function read_args(argv: ReadonlyArray<string>): ParsedArguments | undefined {
+	try {
+		return parseArgs({ args: [...argv], options: OPTIONS, allowPositionals: true, strict: true })
+	} catch {
+		return undefined
+	}
+}
+
+// Exactly one issue number, or the call is refused: `run:status` reports one run, and a second number
+// would print a second issue's state a caller reads as this run's own.
+function valid_issue(positionals: ReadonlyArray<string>): string | undefined {
+	const [first, ...rest] = positionals
+
+	if (first === undefined || rest.length > 0) return undefined
+
+	return ISSUE_NUMBER_PATTERN.test(first) ? first : undefined
+}
+
+function parse(argv: ReadonlyArray<string>): StatusRequest | undefined {
+	const parsed = read_args(argv)
+
+	if (parsed === undefined) return undefined
+
+	const issue_number = valid_issue(parsed.positionals)
+
+	if (issue_number === undefined) return undefined
+
+	const { repo } = parsed.values
+
+	return repo === undefined ? { issue_number } : { issue_number, repo }
+}
+
+// The carry record is keyed on the common git directory every lane of one repository shares, resolved
+// the way `run-carry` resolves it. An unreadable git directory is reported as an unreadable record
+// rather than invented as `none`, the same distinction `run-carry` keeps.
+async function read_carry_record(): Promise<CarryRead> {
+	const directory = await run_carry.repository_directory()
+
+	if (directory === undefined) return { kind: 'unreadable' }
+
+	return run_carry.read_carry(run_carry.carry_path(directory))
+}
+
+async function gather(request: StatusRequest): Promise<StatusReads> {
+	const [state, carry] = await Promise.all([
+		issue_state_cli.read_issue(request.issue_number, request.repo),
+		read_carry_record(),
+	])
+
+	return { state, carry, cost: cost_cli.session_verdict() }
+}
+
+// One note for a read that produced nothing, naming which of the two it was — the same distinction
+// `issue:state` keeps, so a bundled failure still tells a retry from an answer.
+function failure_note(issue_number: string, kind: string): string {
+	return `(issue #${issue_number} not bundled: ${kind})`
+}
+
+function carry_summary(carry: CarryRead): string {
+	if (carry.kind === 'carried') return `${String(carry.carry.merged)}${MERGED_SUFFIX}`
+	if (carry.kind === 'expired') return CARRY_SUMMARY_EXPIRED
+	if (carry.kind === 'unreadable') return CARRY_SUMMARY_UNREADABLE
+
+	return CARRY_SUMMARY_NONE
+}
+
+function carry_detail(carry: CarryRead): string {
+	if (carry.kind === 'carried' || carry.kind === 'expired') {
+		return run_carry.describe_carry(carry.carry)
+	}
+
+	if (carry.kind === 'unreadable') return CARRY_UNREADABLE_NOTE
+
+	return CARRY_NONE_NOTE
+}
+
+function to_parts(issue_number: string, reads: StatusReads): StatusParts {
+	const state = reads.state.kind === 'state' ? reads.state.state : undefined
+	const state_failure = state === undefined ? failure_note(issue_number, reads.state.kind) : ''
+
+	return {
+		issue_number,
+		state,
+		state_failure,
+		cost_verdict: reads.cost,
+		carry_summary: carry_summary(reads.carry),
+		carry_detail: carry_detail(reads.carry),
+	}
+}
+
+// Non-zero when any of the three could not answer: a failed state read, an unreadable carry record, or
+// a session that cannot be priced. A `none` carry is a valid answer — no run is recorded — so it is
+// not a failure, exactly as `issue:state` treats a resolved state.
+function exit_code(reads: StatusReads): number {
+	const is_complete =
+		reads.state.kind === 'state' &&
+		reads.carry.kind !== 'unreadable' &&
+		reads.cost !== cost_cli.UNMEASURABLE_VERDICT
+
+	return is_complete ? SUCCESS_EXIT_CODE : FAILURE_EXIT_CODE
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const request = parse(argv)
+
+	if (request === undefined) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const reads = await gather(request)
+
+	console.info(run_status.format_report(to_parts(request.issue_number, reads)))
+
+	return exit_code(reads)
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const run_status_cli = { USAGE, parse, run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { run_status_cli }

package/scripts/run/run-status.ts

@@ -0,0 +1,77 @@
+import { issue_state, type IssueState } from '#scripts/issue/issue-state'
+
+// `josh run:status <N>` — the read-only status a run glances at, assembled into one report
+// (joshuafolkken/kit#2165). A run reads three independent facts to know where it stands — the issue's
+// own state, whether the session has crossed the hand-off budget, and its own carry counters — and
+// the procedure had it type `issue:state`, `cost --cut` and `run:carry` as three separate steps. This
+// joins the answers those three commands give, reusing each rather than reproducing it.
+//
+// **It is read-only, and that is the whole point** — the merge event has its own composite
+// (`run:merge`), and the pre-edit reads have theirs (`run:prep`); what was left was the passive glance
+// a resumed session or a non-merge decision takes, which must not write. `run:hold`'s claim and
+// `run:progress`'s clock mark are excluded for exactly that reason.
+//
+// The leading summary line carries the three facts on one line — the state, the cost verdict and the
+// carry summary — so the glance is read off the first line without parsing the sections below it.
+
+const SUMMARY_PREFIX = 'status #'
+const STATE_LABEL = 'state: '
+const COST_LABEL = 'cost: '
+const RUN_LABEL = 'run: '
+const FIELD_SEPARATOR = ' · '
+const SUMMARY_DASH = ' — '
+const UNKNOWN = '?'
+const STATE_HEADER = '=== state ==='
+const COST_HEADER = '=== cost ==='
+const RUN_HEADER = '=== run ==='
+const SECTION_SEPARATOR = '\n\n'
+
+interface StatusParts {
+	issue_number: string
+	// `undefined` when the state read failed; `state_failure` then carries the note that stands in for
+	// the three-line block, so a bundled failure never prints as an empty state.
+	state: IssueState | undefined
+	state_failure: string
+	cost_verdict: string
+	// The one-liner form (`2 merged`, `none`, `unreadable`) and the full body, computed by the CLI so
+	// this formatter stays a pure string join, exactly as `run-prep` computes its latest scope.
+	carry_summary: string
+	carry_detail: string
+}
+
+function summary(parts: StatusParts): string {
+	const state_value = parts.state === undefined ? UNKNOWN : parts.state.state
+	const fields = [
+		`${STATE_LABEL}${state_value}`,
+		`${COST_LABEL}${parts.cost_verdict}`,
+		`${RUN_LABEL}${parts.carry_summary}`,
+	]
+
+	return `${SUMMARY_PREFIX}${parts.issue_number}${SUMMARY_DASH}${fields.join(FIELD_SEPARATOR)}`
+}
+
+// The state's three lines come from `issue:state`'s own formatter, so the spelling a document compares
+// against — `human_review: yes` included — is the one this bundle prints.
+function state_body(parts: StatusParts): string {
+	return parts.state === undefined
+		? parts.state_failure
+		: issue_state.format_issue_state(parts.state)
+}
+
+function section(header: string, body: string): string {
+	return `${header}\n${body}`
+}
+
+function format_report(parts: StatusParts): string {
+	return [
+		summary(parts),
+		section(STATE_HEADER, state_body(parts)),
+		section(COST_HEADER, parts.cost_verdict),
+		section(RUN_HEADER, parts.carry_detail),
+	].join(SECTION_SEPARATOR)
+}
+
+const run_status = { COST_HEADER, RUN_HEADER, STATE_HEADER, SUMMARY_PREFIX, format_report }
+
+export type { StatusParts }
+export { run_status }

package/scripts/run/run-step-cli.ts

@@ -0,0 +1,111 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { doctor_consumer } from '#scripts/doctor/doctor-consumer'
+import { hook_decision } from '#scripts/josh/hook-decision'
+import { find_package_directory } from '#scripts/josh/josh-logic'
+import { lane_child_marker } from '#scripts/lane/lane-child-marker'
+import { run_carry, type CarryRead } from './run-carry'
+import { run_event_scope } from './run-event-scope'
+import { run_event_stream } from './run-event-stream'
+import { run_prep_cli } from './run-prep-cli'
+import { run_step, type StepInput } from './run-step'
+
+// `josh run:step <N>` — print the run's next single action, computed from the event stream, the carry
+// record and the issue state (joshuafolkken/kit#2248). It reads exactly those three, never the
+// conversation: the issue facts through `run:prep`'s own gather (so this and `run:next` never answer
+// from different reads), the newest event off the stream, and the carry record's kind. The reader runs
+// the printed line, returns the result through `run:event`, and asks again — the loop `run:step`
+// exists to close.
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const ARGV_OFFSET = 2
+const USAGE = 'Usage: josh run:step <issue-number>'
+// The opt-in switch that gates the end-of-run retrospective (joshuafolkken/kit#2370). Read here rather
+// than in `run-step.ts` so the position logic stays a pure function of its input; it defaults off, so an
+// unset variable prints no retrospective step.
+const RETROSPECTIVE_ENV_KEY = 'JOSH_RETROSPECTIVE'
+
+interface RunReads {
+	carry_kind: CarryRead['kind']
+	is_retrospective_done: boolean
+	last_event: string | undefined
+}
+
+// The run-level reads, keyed on the common git directory both the carry and the event stream share. A
+// directory that cannot be read leaves the position unknowable, which `next_action` answers `unknown`.
+function read_run(directory: string | undefined, issue_number: string): RunReads {
+	if (directory === undefined) {
+		return { carry_kind: 'unreadable', is_retrospective_done: false, last_event: undefined }
+	}
+
+	const carry = run_carry.read_carry(run_carry.carry_path(directory))
+	const events = run_event_stream.read_events(run_event_stream.target_of(directory))
+	// The last event *within this invocation's scope*, not the raw newest one: a stale event a previous
+	// invocation left on the stream must not be read as this run's position (joshuafolkken/kit#2395). The
+	// observed defect was a `run:step` that printed `wait` on a fresh run because an old `child-launch` was
+	// still the stream's tail. Another issue's detached ship supervisor is left out the same way
+	// (joshuafolkken/kit#2428).
+	const last = run_event_scope.last_issue_event(
+		events,
+		run_event_scope.scope_of(carry),
+		issue_number,
+	)
+
+	return {
+		carry_kind: carry.kind,
+		is_retrospective_done: run_carry.retrospective_done_of(carry),
+		last_event: last?.kind,
+	}
+}
+
+async function gather(issue_number: string): Promise<StepInput> {
+	const reads = await run_prep_cli.gather(issue_number)
+	const parts = run_prep_cli.to_parts(issue_number, reads)
+	const run_reads = read_run(await run_carry.repository_directory(), issue_number)
+
+	return {
+		issue_number,
+		state: parts.state?.state,
+		is_human_review: parts.state?.is_human_review ?? false,
+		latest_scope: parts.latest_scope,
+		last_event: run_reads.last_event,
+		carry_kind: run_reads.carry_kind,
+		is_retrospective_done: run_reads.is_retrospective_done,
+		is_lane_child: lane_child_marker.is_child_of(process.cwd()),
+		is_consumer: doctor_consumer.is_kit_consumer(find_package_directory(process.cwd())),
+		is_retrospective_enabled: hook_decision.is_switch_opt_in(RETROSPECTIVE_ENV_KEY),
+		has_changes: parts.has_changes,
+	}
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const issue_number = run_prep_cli.parse_number(argv)
+
+	if (issue_number === undefined) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const input = await gather(issue_number)
+
+	console.info(run_step.next_action(input).line)
+
+	// A state that could not be read exits non-zero, exactly as `run:prep` and `run:next` exit on the
+	// same failure, so a position missing its issue state is never read as a confident next step.
+	return input.state === undefined ? FAILURE_EXIT_CODE : SUCCESS_EXIT_CODE
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	// Load `.env` on the real command path only, so `JOSH_RETROSPECTIVE` set there reaches `gather`; the
+	// unit tests call `run`/`gather` directly and are never swayed by a developer's `.env`.
+	hook_decision.load_environment_file()
+	process.exitCode = await run(argv)
+}
+
+const run_step_cli = { USAGE, gather, main, run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { run_step_cli }