@joshuafolkken/kit 1.872.0

package/scripts/run/run-progress.ts

@@ -0,0 +1,366 @@
+// `josh run:progress` — the one line an unattended run prints when it has gone quiet, and the clock
+// that decides when that is (joshuafolkken/kit#1520).
+//
+// **The trigger is silence, not a timer.** An `epicrun` reports when a child merges or is parked, and
+// a child is 20–46 minutes of wall clock; between those two events it says nothing at all, so the
+// person watching has to type "how is it going" to find out — the polling this command exists to
+// remove. What it deliberately does **not** do is print on a fixed clock: the interval is measured
+// from the last report of *any* kind, so a heartbeat never lands immediately behind a real one, where
+// it would be noise rather than news. `--mark` is how the run tells this clock a real report happened.
+//
+// **A line that could say "still running" is a line not worth printing.** Five minutes was measured in
+// live use on 2026-09-07 and 6 of 15 reports carried no changed number at all, which is the same
+// information as silence. Ten was measured next and was still short of a stage change, so the default
+// is twenty minutes (joshuafolkken/kit#1570): a child measures 20–46 minutes, and twenty gives one to
+// two reports per child rather than a run of lines saying what the last one said. Every field below is
+// re-read on each tick rather than remembered — a child's labels, whether a pull request exists yet,
+// which lanes are open, the load average, and how long the whole set has been identical.
+//
+// **The interval is kept here so one number answers for both halves of the mechanism.** The watcher
+// asks `is_due` before it prints, and the trigger-delivered rule that refuses an early heartbeat
+// (`scripts/rules/early-heartbeat.ts`) asks the same two functions rather than carrying a second copy
+// of the clock — a guard that could disagree with the watcher it guards is worse than no guard.
+//
+// **Nothing here reports a verification result.** No gate conclusion, no CI conclusion, no check
+// rollup: this module reads none of them, and a result nobody read must never be printed as one. What
+// it prints about a pull request is that one exists and what state GitHub calls it — which is a read
+// it actually performs.
+//
+// **The line also says *when* it was observed, and not only how long the silence had run**
+// (joshuafolkken/kit#1560). A relative figure means something only while the reports keep coming: an
+// `epicrun` suspended overnight resumed and read its own `quiet 11m` as if no time had passed, and
+// concluded the machine's clock was broken when it matched GitHub's `Date` header to the second. Three
+// decisions follow from that, and each is a decision rather than a default:
+//
+// - **The date is carried, not just the clock time.** The confusion above happened across a day
+//   boundary, so an `HH:MM` alone would have left the same hole open.
+// - **The local clock leads, and UTC is printed beside it.** The local half is the one a person can
+//   act on without converting anything, which is what UTC alone denied a reader seven hours from it
+//   (joshuafolkken/kit#1589). UTC is kept rather than replaced: the line is read from other machines
+//   and from cloud sessions, and joshuafolkken/kit#1245 already paid for a timestamp rendered in the
+//   reader's zone making one process look like a stranger. The printed offset ties the two halves
+//   together, so a reader on a third machine can place both.
+// - **It is added beside the elapsed figures, never in place of them.** How long it has been quiet and
+//   when the observation was taken are two different facts, and neither can be reconstructed from the
+//   other without knowing the answer already.
+
+const DEFAULT_INTERVAL_MINUTES = 20
+// The one name for the setting, so the watcher and the guard read the same variable rather than two
+// spellings of it.
+const INTERVAL_KEY = 'JOSH_PROGRESS_INTERVAL_MINUTES'
+const MS_PER_MINUTE = 60_000
+const MS_PER_SECOND = 1000
+const DEFAULT_INTERVAL_MS = DEFAULT_INTERVAL_MINUTES * MS_PER_MINUTE
+
+// What one child looked like on this tick. `pr_state` is `run_preflight`'s own vocabulary rather than
+// a second spelling of it — `none` / `open` / `merged` / `closed`.
+interface ChildObservation {
+	issue: string
+	labels: ReadonlyArray<string>
+	pr_state: string
+}
+
+interface LaneObservation {
+	issue: string
+	state: string
+}
+
+interface Observations {
+	children: ReadonlyArray<ChildObservation>
+	lanes: ReadonlyArray<LaneObservation>
+	load_average: number
+	// Absent when no transcript path was given, and absent is printed as absent. Guessing an age for
+	// a file nobody named would be exactly the unread result this command refuses to print.
+	record_age_ms: number | undefined
+}
+
+// How long the *changing* part of the observation has been identical. Carried between ticks by the
+// caller, because the loop is the only thing that lives across them.
+interface ProgressState {
+	key: string
+	unchanged_since_ms: number
+}
+
+const NO_LANES = 'none'
+// The children slot when the run has started but no child carries `in-progress` yet
+// (joshuafolkken/kit#1900). It is an observed fact — zero in-progress children — not a guess about
+// what will appear: `read_observations` returns an observation at all only because a mechanical record
+// (a lane, a hold, or a carried budget) says a run is underway, and the lanes field beside this one
+// carries whatever evidence exists.
+const NO_CHILD_YET = 'no in-progress child yet'
+// The fifth line's value when there is no scheduled next report. The command always supplies one, so
+// this is the migrated form of the rule `backlogrun.md` used to hold — a line with no `next` field says
+// the field was absent rather than inventing a time (joshuafolkken/kit#2026). `format_report` is a pure
+// renderer, so its contract states the absence rather than assuming a stamp is always there.
+const NO_NEXT = 'none'
+const QUIET_MARKER = '⏳'
+// `1970-01-01T00:00:00.000Z` cut after the minutes. Seconds are dropped because the interval this line
+// breaks is measured in minutes, and a heartbeat that claims a precision nobody uses is noise.
+const STAMP_END = 16
+// Two digits for every calendar and clock field the local half prints, and for each half of the offset.
+const PAD_WIDTH = 2
+const MINUTES_PER_HOUR = 60
+
+function to_minutes(elapsed_ms: number): number {
+	return Math.floor(elapsed_ms / MS_PER_MINUTE)
+}
+
+function format_minutes(elapsed_ms: number): string {
+	return `${String(to_minutes(elapsed_ms))}m`
+}
+
+function pad(value: number): string {
+	return String(value).padStart(PAD_WIDTH, '0')
+}
+
+/**
+ * The local clock's offset from UTC, in whole minutes, signed the way a reader expects to see it.
+ *
+ * `getTimezoneOffset` counts minutes the local zone is *behind* UTC, so the sign is inverted here — a
+ * zone ahead of UTC answers a negative number there and has to read `+`.
+ *
+ * **It is rounded**, because a historic offset is not a whole number of minutes: `Asia/Kathmandu` was
+ * `+05:41:16` until 1986, so a stamp taken at an instant in that era answers `-341.2666…` and the
+ * minutes field would print `41.26666666666667` rather than `41`.
+ */
+function offset_minutes(date: Date): number {
+	return Math.round(-date.getTimezoneOffset())
+}
+
+/** That offset written `+HH:MM` or `-HH:MM`, from the same rounded minute total the stamp is built on. */
+function format_offset(total_minutes: number): string {
+	const sign = total_minutes < 0 ? '-' : '+'
+	const absolute = Math.abs(total_minutes)
+
+	return `${sign}${pad(Math.floor(absolute / MINUTES_PER_HOUR))}:${pad(absolute % MINUTES_PER_HOUR)}`
+}
+
+/**
+ * The instant this observation was taken, on the local clock and in UTC, with its date on both.
+ *
+ * **The local half leads because it is the half a person can act on.** The line used to carry UTC
+ * alone, and on a machine seven hours ahead every stamp in the report was a number the reader had to
+ * convert before it meant anything — which is the same failure joshuafolkken/kit#1560 filed, arriving
+ * from the other side: a stamp nobody can place is a stamp nobody reads.
+ *
+ * **UTC is kept beside it rather than replaced.** The reason it was pinned is real and unchanged: the
+ * line is relayed to other machines and read in cloud sessions, and joshuafolkken/kit#1245 already
+ * paid for a timestamp rendered in the reader's zone making one process look like a stranger. Printing
+ * both costs twenty-five characters and leaves neither reader guessing — the offset is what ties the
+ * two halves together, so a reader on a third machine can place the local half as well.
+ *
+ * **The local half is read off the instant shifted by that same rounded offset, never off `getHours`
+ * and `getMinutes`.** Those truncate the seconds of a sub-minute offset while the offset beside them
+ * is rounded, so the two would disagree by a minute in a zone such as `Africa/Monrovia` (`-00:44:30`
+ * in 1970) and the stamp would no longer parse back to the instant it was taken at. Shifting first and
+ * reading UTC fields off the result makes the two halves consistent by construction.
+ *
+ * It reads the `now_ms` the line is already formatted against rather than calling a clock of its own,
+ * so the stamp can never disagree with the elapsed figures printed beside it.
+ */
+function format_observed_at(now_ms: number): string {
+	const minutes = offset_minutes(new Date(now_ms))
+	const local = new Date(now_ms + minutes * MS_PER_MINUTE)
+	const day = `${String(local.getUTCFullYear())}-${pad(local.getUTCMonth() + 1)}-${pad(local.getUTCDate())}`
+	const clock = `${pad(local.getUTCHours())}:${pad(local.getUTCMinutes())}${format_offset(minutes)}`
+
+	return `${day} ${clock} / ${new Date(now_ms).toISOString().slice(0, STAMP_END)}Z`
+}
+
+/**
+ * The part of an observation that is compared across ticks.
+ *
+ * **The load average and the record age are deliberately left out.** Both move on every tick by
+ * construction, so including either would make "unchanged" impossible to reach and would throw away
+ * the one field that says a run may be stuck. What is left is the set that only moves when the run
+ * itself moves: which children are in flight, what they carry, and which lanes are open.
+ */
+function observation_key(observations: Observations): string {
+	return JSON.stringify({ children: observations.children, lanes: observations.lanes })
+}
+
+/**
+ * The unchanged-since clock, carried forward when the key matches and restarted when it does not.
+ *
+ * The first tick has no previous state and starts the clock at `now_ms`, which reads as `unchanged 0m`
+ * — true, and honest about the fact that nothing has been compared yet.
+ */
+function next_state(
+	previous: ProgressState | undefined,
+	key: string,
+	now_ms: number,
+): ProgressState {
+	if (previous?.key === key) return previous
+
+	return { key, unchanged_since_ms: now_ms }
+}
+
+function format_child(child: ChildObservation): string {
+	const labels = child.labels.length > 0 ? child.labels.join(',') : '(no labels)'
+
+	return `#${child.issue} ${labels} PR:${child.pr_state}`
+}
+
+// An empty set is the pre-label stage, said as such rather than left as a blank slot between the
+// separators (joshuafolkken/kit#1900). After that change a `read_observations` result carries no
+// children exactly when a run has started and none has reached `in-progress` yet, so this is the one
+// place the two cases are told apart on the line.
+function format_children(children: ReadonlyArray<ChildObservation>): string {
+	if (children.length === 0) return NO_CHILD_YET
+
+	return children.map((child) => format_child(child)).join(' · ')
+}
+
+function format_lanes(lanes: ReadonlyArray<LaneObservation>): string {
+	if (lanes.length === 0) return NO_LANES
+
+	return lanes.map((lane) => `${lane.issue}:${lane.state}`).join(' ')
+}
+
+// Absent is said, never filled in. A run started without a transcript path prints `unread` here, which
+// is what it is.
+function format_record(record_age_ms: number | undefined): string {
+	return record_age_ms === undefined ? 'unread' : `+${format_minutes(record_age_ms)}`
+}
+
+interface LineTiming {
+	// The interval in force, already resolved by `run-progress-config.ts` → `resolve_interval_ms`. It
+	// is passed in rather than read here so that the printed schedule and the clock `is_due` consults
+	// can never be two different numbers.
+	interval_ms: number
+	now_ms: number
+	quiet_since_ms: number
+	unchanged_since_ms: number
+}
+
+/**
+ * When the next line is due if the silence holds — printed, never left for a reader to work out.
+ *
+ * **The two inputs were both here already and only one of them was printed** (joshuafolkken/kit#1726).
+ * `backlogrun.md` asked the run to derive this from the `at` stamp plus the interval in force, and a run
+ * that derives a time by hand eventually derives it wrong: one report reached a person as `20:1x`,
+ * placeholder digits and all. Every comparable judgement in this repository has moved to the command
+ * that already holds the inputs — `run:hold`, `delegate`, `review:level`, `latest:scope` — and
+ * this is that same move for one value.
+ *
+ * **It is a schedule rather than an observation, and the two conditions on it are said in prose**
+ * (`docs/josh-commands.md` → `josh run:progress`): it holds only while the silence continues, and a
+ * real report arriving first restarts the clock through `--mark` and supersedes it. The line printing
+ * it is itself a report, so the clock starts at this observation.
+ */
+function format_next_report(now_ms: number, interval_ms: number): string {
+	return format_observed_at(now_ms + interval_ms)
+}
+
+// The already-formatted field strings the five labelled lines are built from. They are kept as strings
+// rather than the raw observation so that `format_report` stays a pure renderer the tests can drive with
+// an absent `next`, which is the migrated home of the doc's absent-field rule.
+interface ReportFields {
+	observed_at: string
+	quiet: string
+	unchanged: string
+	children: string
+	lanes: string
+	load: string
+	record: string
+	next: string | undefined
+}
+
+// `next none` when there is no scheduled report, the stamp otherwise — the absence said the same way the
+// other absent fields are (`record unread`, `lanes none`).
+function format_next_line(next: string | undefined): string {
+	return `next ${next ?? NO_NEXT}`
+}
+
+/**
+ * The five labelled lines a quiet run prints — one field group per line, a label in front of every
+ * field — so a person reads them without anything downstream re-labelling them (joshuafolkken/kit#2026).
+ * The command used to emit one `·`-joined run of values that `backlogrun.md` asked the parent to rewrite
+ * by hand every interval; the labels and the line breaks live here now, so the parent relays the output
+ * verbatim and rounds, rephrases or re-labels nothing.
+ *
+ * The observation instant leads and the scheduled next closes it, for the reason the single line kept
+ * them at its two ends: the first field says whether everything after it is still about now, and the
+ * last is the one field about a moment that has not happened yet.
+ */
+function format_report(fields: ReportFields): string {
+	return [
+		`${QUIET_MARKER} at ${fields.observed_at}`,
+		`quiet ${fields.quiet} · unchanged ${fields.unchanged}`,
+		`children ${fields.children}`,
+		`lanes ${fields.lanes} · load ${fields.load} · record ${fields.record}`,
+		format_next_line(fields.next),
+	].join('\n')
+}
+
+/**
+ * The observations rendered into those five lines. It reads `now_ms` for both the observation stamp and
+ * the scheduled next so the two can never disagree, and hands `format_report` already-formatted strings
+ * so the rendering has one home.
+ */
+function format_line(observations: Observations, timing: LineTiming): string {
+	return format_report({
+		observed_at: format_observed_at(timing.now_ms),
+		quiet: format_minutes(timing.now_ms - timing.quiet_since_ms),
+		unchanged: format_minutes(timing.now_ms - timing.unchanged_since_ms),
+		children: format_children(observations.children),
+		lanes: format_lanes(observations.lanes),
+		load: observations.load_average.toFixed(1),
+		record: format_record(observations.record_age_ms),
+		next: format_next_report(timing.now_ms, timing.interval_ms),
+	})
+}
+
+/**
+ * Whether the silence has run long enough to be worth breaking.
+ *
+ * `>=` rather than `>`: the loop wakes on a timer that can land a millisecond early or late, and a
+ * strict comparison there costs a whole extra sleep for no reason anyone could observe.
+ */
+function is_due(last_report_ms: number, now_ms: number, interval_ms: number): boolean {
+	return now_ms - last_report_ms >= interval_ms
+}
+
+/**
+ * One setting's minutes, or `undefined` for everything that is not a positive number.
+ *
+ * **Invalid answers `undefined` rather than throwing**, the reading `JOSH_CI_TIMEOUT_SECONDS` already
+ * uses: this runs unattended in the background, and a run that dies on a typo in an optional setting
+ * has removed the reporting the setting was there to tune. Which source is asked next, and in what
+ * order, is `run-progress-config.ts` → `resolve_interval_ms`; this module answers about one value and
+ * asks nothing else, which is what lets both the watcher and the guard read it the same way.
+ */
+function minutes_from(raw: string | undefined): number | undefined {
+	const minutes = Number(raw)
+
+	if (raw === undefined || raw.trim() === '' || !Number.isFinite(minutes) || minutes <= 0) {
+		return undefined
+	}
+
+	return minutes
+}
+
+const run_progress = {
+	DEFAULT_INTERVAL_MINUTES,
+	DEFAULT_INTERVAL_MS,
+	INTERVAL_KEY,
+	MS_PER_MINUTE,
+	MS_PER_SECOND,
+	NO_CHILD_YET,
+	NO_NEXT,
+	format_child,
+	format_children,
+	format_lanes,
+	format_line,
+	format_next_line,
+	format_next_report,
+	format_record,
+	format_report,
+	is_due,
+	minutes_from,
+	next_state,
+	observation_key,
+}
+
+export type { ChildObservation, LaneObservation, Observations, ProgressState }
+export { run_progress }

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

@@ -0,0 +1,71 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { git_followup_pending } from '#scripts/git/git-followup-pending'
+import { release_scope_cli } from '#scripts/release/release-scope-cli'
+import { run_carry } from './run-carry'
+import { run_event_scope, type EventScope } from './run-event-scope'
+import { run_event_stream, type RunEvent } from './run-event-stream'
+import { run_event_stream_emit } from './run-event-stream-emit'
+import { run_report } from './run-report'
+
+// `josh run:report` — the session-facing report, generated from the run's event stream rather than
+// composed by hand (joshuafolkken/kit#2249). It reads the events the run appended, asks `release:scope`
+// the same question `josh followup` already asks, and prints `run_report.build_report` of the two. The AI
+// writes only Step 0's three lines (Now / Change / Check), which `report-format.md` names as the half a
+// machine cannot answer; this owns the mechanical half — what merged, what parked and why, what was cut,
+// and whether a release is owed.
+//
+// **The body it prints is the Telegram body too.** `josh notify --body-file <file>` sends exactly this
+// output, so the summary a session shows and the message a person reads off-screen are one string from one
+// generator, never a second wording of the same facts.
+
+const SUCCESS_EXIT_CODE = 0
+
+// An absent or unreadable stream is an empty run, the same fail-quiet direction the stream's own reader
+// takes — a report with no events is a report, not an error.
+async function read_stream(): Promise<ReadonlyArray<RunEvent>> {
+	const target = await run_event_stream_emit.stream_target()
+
+	if (target === undefined) return []
+
+	return run_event_stream.read_events(target)
+}
+
+// The invocation this report covers, taken from the run record that already holds the start time
+// (joshuafolkken/kit#2393). A checkout whose git directory cannot be resolved has no record to read, which is
+// the same undetermined answer an absent record gives — and neither one falls back to the whole stream.
+async function read_scope(): Promise<EventScope> {
+	const directory = await run_carry.repository_directory()
+
+	if (directory === undefined) return run_event_scope.UNKNOWN_EVENT_SCOPE
+
+	return run_event_scope.scope_of(run_carry.read_carry(run_carry.carry_path(directory)))
+}
+
+// The three reads are independent, so they are issued together rather than one after another — the stream, the
+// pending-merge count and the run record share no input.
+async function run(): Promise<number> {
+	const [events, pending, scope] = await Promise.all([
+		read_stream(),
+		git_followup_pending.read_pending({}),
+		read_scope(),
+	])
+	const release = release_scope_cli.decide(pending)
+
+	process.stdout.write(`${run_report.build_report({ events, release, scope })}\n`)
+
+	return SUCCESS_EXIT_CODE
+}
+
+async function main(): Promise<void> {
+	process.exitCode = await run()
+}
+
+const run_report_cli = {
+	main,
+	run,
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main()
+
+export { run_report_cli }

package/scripts/run/run-report.ts

@@ -0,0 +1,78 @@
+import { release_scope_cli, type Decision } from '#scripts/release/release-scope-cli'
+import { run_event_scope, type EventScope } from './run-event-scope'
+import { run_event_stream, type RunEvent } from './run-event-stream'
+
+// The session-facing report generated *from* the run's event stream, rather than composed by hand each
+// time (joshuafolkken/kit#2249). #2205 gave the run a typed, ordered stream of what happened — a plan, a
+// launch, a merge, a park, a cut — and `format_event` already single-sources what one of those reads as.
+// What was never single-sourced is the report a person receives: `backlogrun-progress.md` defined the
+// epic completion summary in prose ("naming what was merged, what was parked and why, and what was
+// filed"), so the AI reassembled the wording every run and two runs' summaries never lined up.
+//
+// **This is that generator, and it owns nothing `format_event` owns.** Each event line is `format_event`'s
+// verbatim — the merges, the parks with their reason in the text, the cuts — so the enumeration is the
+// stream rendered, not a second rendering of it. The only thing this adds is the release tail, which is
+// not on the stream: whether a release is owed is `release:scope`'s answer, appended once at the end.
+//
+// **The Telegram body is this same string.** `run:report` prints it, and `josh notify --body-file` sends
+// exactly what was printed, so the body a person reads off-screen and the summary a session shows are one
+// text with one generator — the "no second format" the acceptance criteria pin.
+//
+// **And it covers one invocation, not the whole stream** (joshuafolkken/kit#2393, reported a second time
+// after #2308 was closed with no fix behind it). The stream outlives an invocation by design — it is the
+// repository's event log, not this run's — so a generator handed every event renders every run that ever
+// appended one. Two days of merges arrived in one completion summary, and the Telegram body built from that
+// output was rejected for length, which is the failure the generated report exists to prevent. The scope is
+// therefore an **input**: the caller answers which invocation this is, from the run record that already
+// holds the start time, and a scope nobody could determine prints a notice rather than everything. **The
+// scoping itself is `run-event-scope.ts`'s** (joshuafolkken/kit#2395), shared with every other stream
+// consumer rather than kept private here.
+
+const LINE_SEPARATOR = '\n'
+
+// What an undetermined scope prints in place of every event. It is a line rather than silence for the reason
+// `release:scope` keeps `unknown` apart from `skip`: a reader given no line at all would read the empty
+// report as an empty run, which is the rounding the criteria forbid.
+const UNKNOWN_SCOPE_NOTICE =
+	'Could not determine which invocation these events belong to, so none are shown rather than the whole stream. Begin a run record with `pnpm josh run:carry --begin` first.'
+
+interface ReportInput {
+	events: ReadonlyArray<RunEvent>
+	release: Decision
+	scope: EventScope
+}
+
+// The release verdict as the report's closing line, or nothing. `required` closes with the request and
+// the exact command, and `unknown` says `unknown` — both carried verbatim in `release:scope`'s own reason,
+// so the wording is that command's and not a second copy. **`skip` alone is silent**: appending a line for
+// it is what would round `unknown` toward "nothing is owed", the mistake the criteria forbid, so the two
+// stay distinguishable by the presence of the line itself.
+function release_tail(release: Decision): string | undefined {
+	if (release.scope === release_scope_cli.SKIPPED_SCOPE) return undefined
+
+	return release.reason
+}
+
+// The report: this invocation's events as `format_event`'s lines, then the release tail when there is one.
+// Handed the same events, scope and verdict it returns the same string, which is what the determinism test
+// pins — nothing here reads a clock or the environment. The scoping is `run-event-scope.ts`'s, shared with
+// every other stream consumer (joshuafolkken/kit#2395).
+function build_report(input: ReportInput): string {
+	const scoped = run_event_scope.scoped_events(input.events, input.scope)
+	const lines =
+		scoped === undefined
+			? [UNKNOWN_SCOPE_NOTICE]
+			: scoped.map((event) => run_event_stream.format_event(event))
+	const tail = release_tail(input.release)
+
+	return [...lines, ...(tail === undefined ? [] : [tail])].join(LINE_SEPARATOR)
+}
+
+const run_report = {
+	UNKNOWN_SCOPE_NOTICE,
+	build_report,
+	release_tail,
+}
+
+export type { ReportInput }
+export { run_report }

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

@@ -0,0 +1,130 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { review_brief_cli } from '#scripts/review/review-brief-cli'
+import { review_stamps } from '#scripts/review/review-stamps'
+import { run_review, type GateState, type ReviewTiming } from './run-review'
+import { run_review_steps } from './run-review-steps'
+
+// `josh run:review` — one call that leaves `josh gate` running in the background and prints the whole
+// `/code-review` brief, so a lane child launches the two together and they overlap
+// (joshuafolkken/kit#2179). It composes `josh gate` and `josh review:brief` and changes neither: the
+// gate is the same command spawned detached, and the brief is `review:brief` run unchanged, so the
+// nonce/checkout contract `review:attest --check` enforces is minted exactly as before.
+//
+// **The default mode opens the pair; `--join` closes it.** The child runs the default, reads the brief
+// off stdout, launches the review subagent, and — once it returns — runs `--join`, which waits for the
+// gate to finish, records the overlap, and exits non-zero if the gate came back red. That exit code is
+// what makes "a red gate is not adopted over" a mechanical guarantee rather than an ordering the child
+// used to get for free (`run-review.ts` → `adopt_verdict`).
+
+const ARGV_OFFSET = 2
+const JOIN_FLAG = '--join'
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const USAGE = 'Usage: josh run:review [--join]'
+
+function now_iso(): string {
+	return new Date().toISOString()
+}
+
+// The join exits 0 only on a green gate. `--join` is run before the review verdict is acted on, so a
+// non-zero exit here is what stops a run adopting a review over a red gate.
+function join_exit_code(state: GateState): number {
+	return run_review.adopt_verdict(state === run_review.GATE_GREEN) === run_review.ADOPT
+		? SUCCESS_EXIT_CODE
+		: FAILURE_EXIT_CODE
+}
+
+const JOIN_HINT =
+	'Gate is running in the background. Launch the /code-review subagent with the brief above; when it returns, run `pnpm josh run:review --join` to join the gate and check its verdict before committing.'
+
+async function run_start(): Promise<number> {
+	const gate_started_at = now_iso()
+	const launch = run_review_steps.launch_gate()
+
+	if (launch.kind === 'failed') {
+		process.stderr.write(`the background gate could not be started: ${launch.note}\n`)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	await run_review_steps.mark_gate_starting()
+	run_review_steps.write_timing_start({ gate_started_at, review_started_at: now_iso() })
+	const code = await review_brief_cli.run([])
+
+	// The hint follows a printed brief and nothing else: a brief that refused (a tree the scoped pair
+	// has not been green on) exits non-zero, and a "gate running, launch the review" line under that
+	// refusal would send the child to review a tree there is no brief for.
+	if (code === SUCCESS_EXIT_CODE) process.stderr.write(`${JOIN_HINT}\n`)
+
+	return code
+}
+
+// The gate's own green stamp carries the moment it finished; a red gate leaves none, so the join's own
+// clock is the end there — the review overlapped a gate that ran up to this point either way.
+function gate_ended_at(is_green: boolean): string {
+	if (!is_green) return now_iso()
+
+	return review_stamps.gate_stamp.read()?.taken_at ?? now_iso()
+}
+
+const GREEN_NOTE = 'Gate green — the review verdict may be adopted.'
+const RED_NOTE =
+	'Gate RED — the review verdict is blocked; fix the gate and re-run it before committing.'
+
+function report_gate(state: GateState): void {
+	if (state === run_review.GATE_GREEN) {
+		process.stdout.write(`${GREEN_NOTE}\n`)
+
+		return
+	}
+
+	const log = run_review_steps.read_gate_log()
+
+	if (log !== undefined) process.stdout.write(`${log}\n`)
+	process.stdout.write(`${RED_NOTE}\n`)
+}
+
+function report_timing(timing: ReviewTiming | undefined): void {
+	if (timing === undefined) return
+
+	process.stdout.write(`${run_review.format_timing(timing)}\n`)
+}
+
+async function run_join(): Promise<number> {
+	const state = await run_review_steps.wait_for_gate_finish()
+	const timing = run_review_steps.complete_timing({
+		gate_ended_at: gate_ended_at(state === run_review.GATE_GREEN),
+		review_ended_at: now_iso(),
+	})
+
+	report_gate(state)
+	report_timing(timing)
+
+	return join_exit_code(state)
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	if (argv.length === 0) return await run_start()
+	if (argv.length === 1 && argv[0] === JOIN_FLAG) return await run_join()
+
+	process.stderr.write(`${USAGE}\n`)
+
+	return FAILURE_EXIT_CODE
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const run_review_cli = {
+	JOIN_FLAG,
+	USAGE,
+	join_exit_code,
+	main,
+	run,
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { run_review_cli }