@joshuafolkken/kit 1.872.0

package/scripts/gate/gate-log.ts

@@ -0,0 +1,95 @@
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { stamp_file } from '#scripts/josh/stamp-file'
+
+// The verification gate's full output, kept somewhere the console's size limit cannot reach
+// (joshuafolkken/kit#1227).
+//
+// **The problem is that the only copy of a failure's detail was the console.** `josh gate` buffers
+// every check and prints the failing ones whole, and joshuafolkken/kit#1173 then declared
+// `BASH_MAX_OUTPUT_LENGTH` at 8,000 characters — a cap on what a command may carry into an agent's
+// context, with a measured p99 of 15,989 characters for a Bash call. The verdict is the last line and
+// so always survives, which is why a red gate can never read as green; what does not survive is the
+// middle, and the middle is where the failure says what it was. The escape hatch was to re-run one
+// check by hand, which is a judgement the reader has to make about output they cannot see.
+//
+// So the gate writes every check's output to a file and prints where it is. Nothing about the
+// verdict changes; what changes is that the detail behind it no longer exists only in a window that
+// may have been elided.
+
+const GATE_LOG_PREFIX = 'josh-gate-log-'
+const GATE_LOG_SUFFIX = '.log'
+
+// **The temp directory, per checkout, deterministic — the convention `stamp-file.ts` already
+// defines**, and it is imported rather than re-derived. A file inside the repository would need a
+// gitignore entry here and in every consumer `josh sync` reaches, bought for something nobody keeps.
+// The path is stable across runs, so each gate overwrites the last one's log: one file per checkout,
+// and nothing accumulates.
+function gate_log_path(target?: string): string {
+	return target ?? stamp_file.stamp_path(GATE_LOG_PREFIX, PROJECT_ROOT, GATE_LOG_SUFFIX)
+}
+
+// The header the console already prints for this step, reused verbatim. The gate builds it once and
+// hands it here, so a log section can never name a check differently from the block above it.
+interface GateLogEntry {
+	header: string
+	output: string
+}
+
+function format_gate_log_entry(entry: GateLogEntry): string {
+	return `=== ${entry.header} ===\n${entry.output}\n`
+}
+
+function format_gate_log(entries: ReadonlyArray<GateLogEntry>): string {
+	return entries.map((entry) => format_gate_log_entry(entry)).join('\n')
+}
+
+// **Written on every run that started a check, passing ones included.** Writing only on failure
+// would make the record a judgement about which runs are worth keeping, and the judgement is wrong
+// in both of the cases that already print a body on a green gate: a check that passed with warnings,
+// and one that passed without running. It also costs a reader nothing — the file is overwritten, so
+// a green run leaves exactly as many files behind as a red one. A gate that reused a recorded green
+// result started no check and has nothing to write, which is why this is called from the checked
+// path alone.
+//
+// **A write that fails never changes the verdict.** The log is a convenience for whoever reads the
+// output next, and a temp-directory problem must not turn a green gate red — the same rule the
+// green-gate record and the in-flight marker already follow. `undefined` is that failure, and the
+// notice below says so out loud rather than leaving the reader to notice a missing line.
+function write_gate_log(entries: ReadonlyArray<GateLogEntry>, target?: string): string | undefined {
+	const destination = gate_log_path(target)
+
+	try {
+		return stamp_file.write_text_stamp(destination, format_gate_log(entries))
+	} catch {
+		return undefined
+	}
+}
+
+const LOG_NOTICE_PREFIX = 'full output: '
+const LOG_FAILED_NOTICE = 'full output: could not be written; re-run with `> gate.log 2>&1`'
+
+// **The notice goes immediately *above* the verdict, never below it.** `josh-verdict.ts` documents
+// the gate's verdict as its last line and builds two readers on that: `time-reported-failure.ts`
+// resumes its scan after the verdict, and the `2>&1 | tail -40` in
+// `prompts/collaboration-workflow/output-bounds.md` keeps the end of the output. A line after the
+// verdict would sit inside both of those windows and take the property away for a line that is not
+// the answer. Above it, the path survives a `tail` exactly as the verdict does.
+function format_log_notice(log_path: string | undefined): string {
+	if (log_path === undefined) return `${LOG_FAILED_NOTICE}\n`
+
+	return `${LOG_NOTICE_PREFIX}${log_path}\n`
+}
+
+const gate_log = {
+	format_gate_log,
+	format_log_notice,
+	gate_log_path,
+	GATE_LOG_PREFIX,
+	GATE_LOG_SUFFIX,
+	LOG_FAILED_NOTICE,
+	LOG_NOTICE_PREFIX,
+	write_gate_log,
+}
+
+export type { GateLogEntry }
+export { gate_log }

package/scripts/gate/gate-plan.ts

@@ -0,0 +1,356 @@
+import { availableParallelism } from 'node:os'
+import { josh_verdict } from '#scripts/josh/josh-verdict'
+import { unit_worker_share } from '#scripts/test/unit-worker-share'
+
+// How many of the gate's checks run at once, and how wide the one elastic check may fan out —
+// both derived from the machine rather than fixed at four (joshuafolkken/kit#1258).
+//
+// **The measurement this table is built from.** Apple M3 Pro, 11 logical cores (5 performance +
+// 6 efficiency, about 9 cores of aggregate throughput on this workload), warm caches, each check
+// run alone. `CPU-seconds ÷ wall-seconds` is how many cores the check actually occupies:
+//
+// | check     | wall  | CPU    | cores |
+// | --------- | ----- | ------ | ----- |
+// | lint      |  5.2s |  10.8s |   2.1 |
+// | check     |  1.4s |   2.3s |   1.7 |
+// | cspell    |  1.1s |   1.5s |   1.3 |
+// | test:unit | 12.6s | 107.0s |   8.5 |
+//
+// Two things follow. **The concurrent gate is already the faster shape** — 15.1s together against
+// 19.1s back to back, the median of three interleaved runs on the same tree, and the one pair
+// `verification-gate.ts` and `docs/josh-commands.md` quote too — so this is a widening of an
+// existing win, not a repair of the regression joshuafolkken/kit#1258 was filed for: that was
+// real when the type check and the spell check cost 6.9s and 3.6s of CPU, and joshuafolkken/kit#1256
+// removed it by giving both a cache. **And the unit suite is the only check worth sizing**: it
+// alone accounts for 107 of the 122 CPU-seconds, because vitest opens one worker per core while
+// the other three are one or two processes each.
+
+interface GateCheck {
+	label: string
+	// The `josh` sub-command that defines the check, and the one an appended argument belongs to.
+	target: string
+	// Cores this check holds for as long as it runs — the measured ratio above, floored to whole
+	// cores and never below one. Floored rather than rounded because this is the share the *other*
+	// checks must give up: over-reserving costs the elastic check workers it would have used.
+	// The unit suite reserves nothing: it sizes its own pool from the machine, so it is capped
+	// instead of reserved, and counting it here would reserve cores against itself.
+	reserved_cores: number
+}
+
+const LINT_LABEL = 'lint'
+const TYPE_CHECK_LABEL = 'check'
+const UNIT_LABEL = 'test:unit'
+const BEHAVIOR_LABEL = 'behavior'
+
+// The checks whose warnings must survive the green record: eslint (the `lint` step) and svelte-check
+// (the `check` step) both exit 0 while reporting per-tree warnings a developer needs to see again, so
+// reusing a record taken from such a run would hide them (joshuafolkken/kit#1328). Every other step's
+// warning-shaped output — a Vite config deprecation printed by `test:unit`, say — is not a per-tree
+// finding and repeats every run, so it must not withhold the record. This is what `has_checker_warning`
+// narrows the withholding path down to (joshuafolkken/kit#2318).
+const WARNING_CHECKER_LABELS: ReadonlyArray<string> = [LINT_LABEL, TYPE_CHECK_LABEL]
+
+// The checks that do not fan out across every core, in the order their output is printed. They are
+// named apart from the unit suite because CI runs them on their own runner (joshuafolkken/kit#1226):
+// the unit suite is the only check that fans out across every core, so on a 4-core GitHub runner it
+// and the others spent the whole job taking cores off each other.
+//
+// **The behavior check belongs here, and it reserves no core** (joshuafolkken/kit#2365). It reads one
+// recorded transcript rather than the tree, so it is I/O-bound and a zero reservation leaves
+// `RESERVED_CORES` and the unit worker cap exactly where the other three were measured. Being a static
+// check rather than one appended after the unit suite is what keeps the plan's shape intact: the
+// `--no-unit` set stays "the whole gate minus the unit suite", and a CI runner — which has no recorded
+// transcripts — runs it as a trivial green rather than skipping it.
+const STATIC_CHECKS: ReadonlyArray<GateCheck> = [
+	{ label: LINT_LABEL, target: 'lint', reserved_cores: 2 },
+	{ label: TYPE_CHECK_LABEL, target: 'check', reserved_cores: 1 },
+	{ label: 'cspell', target: 'cspell:dot', reserved_cores: 1 },
+	{ label: BEHAVIOR_LABEL, target: BEHAVIOR_LABEL, reserved_cores: 0 },
+]
+
+// The checks, in the order their output is printed — the static set, then the unit suite last (the
+// one check that fans out across every core, and the one the `--no-unit` split drops).
+const GATE_CHECKS: ReadonlyArray<GateCheck> = [
+	...STATIC_CHECKS,
+	{ label: UNIT_LABEL, target: UNIT_LABEL, reserved_cores: 0 },
+]
+
+// **Selecting is not skipping, and the difference is where the unit suite runs rather than whether
+// it runs.** `josh gate --no-unit` exists for one caller — the CI job that has handed the unit suite
+// to a runner of its own — and every other entry point still gets all four. What makes the narrower
+// set safe is that nothing downstream may mistake it for the full gate: `verification-gate.ts`
+// withholds both the green-gate record and the in-flight marker on a partial run, so a `--no-unit`
+// gate can never tell `josh review:brief` that the unit suite passed on this tree.
+function select_gate_checks(is_unit_included: boolean): ReadonlyArray<GateCheck> {
+	return is_unit_included ? GATE_CHECKS : STATIC_CHECKS
+}
+
+// Asked of the plan rather than of the flag, so the one question "did this gate run the unit suite"
+// has one answer however the plan was built.
+function has_unit_check(checks: ReadonlyArray<GateCheck>): boolean {
+	return checks.some((check) => check.label === UNIT_LABEL)
+}
+
+// What the three non-elastic checks hold between them: 2 + 1 + 1. Reduced over `STATIC_CHECKS`
+// rather than over all four, because that is the set the sentence above names: `resolve_unit_worker_cap`
+// spends this as the cores the unit suite must leave to its siblings, so summing the unit check into
+// it would have the suite subtract its own reservation from its own budget the day that reservation
+// stops being zero. The two sets give the same number today, which is exactly why the narrower one
+// has to be the declared one.
+const RESERVED_CORES: number = STATIC_CHECKS.reduce(
+	(total, check) => total + check.reserved_cores,
+	0,
+)
+
+// The machine the table above was measured on, and the smallest one the cap is applied to.
+//
+// **Below it the plan leaves the unit suite alone**, because four reserved cores are a far larger
+// share of a small machine than of this one — half an 8-core machine against a third of this — and
+// the one measurement that exists says nothing about whether the reservation still pays there.
+// Extrapolating it downward is what would hurt: the suite takes 11.7s at 8 workers and 16.7s at 4,
+// so a rule that handed an 8-core machine four workers would pin the longest check at the slow end
+// of a curve nobody measured on that machine. An unmeasured machine gets the behavior `josh gate`
+// had before this plan existed — vitest sizing its own pool — rather than an extrapolated one, and
+// a 4-core CI runner is far below the line, which is why this leaves CI running exactly as it did.
+const MEASURED_CORES = 11
+
+// At least one check at a time, whatever the machine reports.
+const MIN_CONCURRENCY = 1
+
+// At least one core to plan against, however many gates are sharing the machine. Without it a
+// twelfth lane would divide 11 cores to zero and admit nothing, and `MIN_CONCURRENCY` would be
+// covering for an arithmetic accident rather than for a genuinely tiny machine.
+const MIN_SHARED_CORES = 1
+
+interface GatePlan {
+	// The checks this run fans out to — all four, or the static three when the unit suite has a
+	// runner of its own. Carried on the plan rather than re-derived at each use, so the concurrency,
+	// the printed plan line and the steps that actually run can never describe different sets.
+	checks: ReadonlyArray<GateCheck>
+	// How many checks run at once.
+	concurrency: number
+	// `--maxWorkers` for the unit suite, or `undefined` to leave the choice to vitest.
+	unit_worker_cap: number | undefined
+}
+
+// This gate's share of the machine — the cores it may plan against once the other gates in flight
+// have theirs (joshuafolkken/kit#1547).
+//
+// **At one run this is the identity, and that is the whole argument that solo behavior is
+// unchanged.** `Math.floor(cores / 1)` is `cores`, so a solo gate and a CI runner hand the admission
+// below exactly the number they always handed it — not a number that happens to come out the same,
+// the same number, by arithmetic — and no branch, flag or environment probe stands between the two
+// cases to be got wrong later.
+//
+// **A run count that is not a number leaves the machine undivided, and the clamp is not cosmetic.**
+// `Math.max` propagates `NaN` rather than clamping it, so an unusable count would sail through
+// `MIN_SHARED_CORES`, make every `reserved > share` comparison false and admit all four checks —
+// the exact opposite of what this function is for. `bounded-pool.ts` closes the same hole for the
+// same reason. A count below one is nonsense too and is read as one run, which is the direction
+// that leaves behavior where it was rather than throttling a gate on a bad input.
+function shared_cores(available_cores: number, concurrent_runs: number): number {
+	const runs = Number.isFinite(concurrent_runs)
+		? Math.max(unit_worker_share.SOLO_RUNS, concurrent_runs)
+		: unit_worker_share.SOLO_RUNS
+
+	return Math.max(MIN_SHARED_CORES, Math.floor(available_cores / runs))
+}
+
+// Admit checks in declaration order while the running set's reserved cores still fit **this run's
+// share** of the machine. On a machine running one gate that share is the machine, so this bites
+// only below four cores — the three reserving checks want four between them — and there it is the
+// difference between two checks sharing a core and four fighting over it.
+//
+// **Under concurrency it is the only lever there is, and that is a measurement rather than a
+// preference** (joshuafolkken/kit#1547). `josh gate` starts four checks at once and joshuafolkken/kit#1515
+// sized only the fourth, so six lanes put 18 unbounded checks on 11 cores: measured on that machine,
+// one gate took 254.1s with lint alone at 252.9s against the 5.2s the table above records for it
+// solo. The obvious repair — hand each of the other three a worker count the way the unit suite gets
+// one — **does not exist to be applied**: eslint 10's `--concurrency` defaults to `off` and is
+// already single-threaded, `tsc` is one process, and cspell's CLI exposes no thread count at all.
+// Nothing in those three takes a number, so how many of them run beside each other is the only
+// quantity the gate controls, and dividing the machine before admitting them is how it controls it.
+//
+// **Narrowing is not skipping.** Every one of the four checks still runs, over the same files, and
+// the gate still reports every failure in one pass — `bounded_pool` queues what it does not start,
+// and no check ever rejects (see `run_gate_steps`). What changes is how many are in flight at
+// once, which is scheduling and never coverage.
+function resolve_concurrency(
+	available_cores: number,
+	concurrent_runs: number = unit_worker_share.SOLO_RUNS,
+	checks: ReadonlyArray<GateCheck> = GATE_CHECKS,
+): number {
+	const share = shared_cores(available_cores, concurrent_runs)
+	let admitted = 0
+	let reserved = 0
+
+	for (const check of checks) {
+		reserved += check.reserved_cores
+
+		if (reserved > share) break
+
+		admitted += 1
+	}
+
+	return Math.max(MIN_CONCURRENCY, admitted)
+}
+
+// The cores left once the other three have their share — on the measured machine, 7 of 11, which
+// held the gate's wall time inside run-to-run noise while burning 5–6% less CPU (101s against
+// 107s). A machine smaller than the measured one is left uncapped; see `MEASURED_CORES`.
+//
+// **The table above is a measurement of one gate on an idle machine, and `concurrent_runs` is what
+// says whether that is the situation** (joshuafolkken/kit#1515). Six lanes each reading "11 cores,
+// take 7" put 42 workers on 11 cores, at a load average of 14.97, and the gate had no way to know the
+// other five existed. Where more than one unit run is in flight the machine is divided between them
+// instead, by `unit-worker-share.ts`, which is the same answer `test-unit-guard.ts` gives the pre-push
+// hook. At one run — every solo gate, CI included — the number is exactly what it was.
+//
+// **The shared branch drops `RESERVED_CORES`, knowingly, and it is not a strict improvement.** Each
+// concurrent gate still runs lint, the type check and the spell check beside its unit step, and the
+// share below does not subtract them: on 12 cores a solo gate takes 8 unit workers plus 3 siblings —
+// 11 processes for 12 cores — while two concurrent gates take 6 each plus 3 siblings each, which is 18.
+// The obvious correction, `⌊(cores − RESERVED_CORES × runs) ÷ runs⌋`, is **not** applied because
+// nothing has measured it: it hands two gates on an 11-core machine one worker apiece, against the
+// 11.7s-at-8-workers / 16.7s-at-4 curve the table above was built from, and trading a measured
+// oversubscription for an unmeasured starvation is not an improvement anyone can defend. What *is*
+// measured is the unit half — six concurrent suites went from ten timeouts to none at this share.
+//
+// **joshuafolkken/kit#1547 narrowed `resolve_concurrency` and deliberately left this number alone.**
+// A narrowed gate no longer runs its three siblings *beside* its unit step, so the paragraph above
+// now over-states what the share is competing with — which is an argument for widening it, and
+// widening it is exactly the unmeasured move that paragraph refuses. The number #1515 measured stays
+// until something measures a better one on this machine.
+//
+// **The count is a parameter rather than a read.** This module stays a pure function of its inputs, so
+// its own assertions are about arithmetic and not about what happened to be running while they ran;
+// `verification-gate.ts` is where the machine is asked.
+function resolve_unit_worker_cap(
+	available_cores: number,
+	concurrent_runs: number = unit_worker_share.SOLO_RUNS,
+): number | undefined {
+	const share = unit_worker_share.resolve_unit_workers(available_cores, concurrent_runs)
+
+	if (share !== undefined) return share
+	if (available_cores < MEASURED_CORES) return undefined
+
+	return available_cores - RESERVED_CORES
+}
+
+// The cores a check reserves from the machine-wide budget while it runs (joshuafolkken/kit#2351). The
+// static checks declare their measured reservation; the unit suite declares the pool it will open,
+// which `unit_worker_cap` has already sized against the runs in flight. **This is the same table, read
+// once**: no second set of weights is introduced, so a change to the measured reservation moves the
+// admission with it.
+//
+// **A solo gate's four weights sum to exactly the core count** — `reserved(2 + 1 + 1) +
+// unit_cap(cores - 4)` is `cores` — which is what lets every check of a lone gate be admitted at once,
+// its concurrency unchanged. A machine below the measured one leaves the unit suite uncapped and reads
+// its weight from the same identity, `cores - RESERVED_CORES` clamped at zero, so the sum is the core
+// count there too.
+function check_weight(check: GateCheck, plan: GatePlan, available_cores: number): number {
+	if (check.label !== UNIT_LABEL) return check.reserved_cores
+
+	return plan.unit_worker_cap ?? Math.max(0, available_cores - RESERVED_CORES)
+}
+
+// `availableParallelism()` rather than `cpus().length`: it reports what this process may actually
+// use, so a container with a CPU quota is sized by the quota rather than by the host.
+// The three fields together, for a caller that has already decided the numbers. The gate's own
+// suites need plans the resolver would never produce — a serial one, a capped one — and building
+// them by hand meant restating the check list at every literal, so a field added to `GatePlan` broke
+// each of them individually. One constructor is what keeps a new field from being an edit per plan.
+function plan_of(
+	concurrency: number,
+	unit_worker_cap?: number,
+	checks: ReadonlyArray<GateCheck> = GATE_CHECKS,
+): GatePlan {
+	return { checks, concurrency, unit_worker_cap }
+}
+
+//
+// **The worker cap follows the checks rather than the machine.** A plan with no unit step has no
+// unit suite to size, so it carries no cap — leaving one on would print a worker count for a check
+// this run never starts.
+function resolve_gate_plan(
+	available_cores: number = availableParallelism(),
+	concurrent_runs: number = unit_worker_share.SOLO_RUNS,
+	is_unit_included = true,
+): GatePlan {
+	const checks = select_gate_checks(is_unit_included)
+
+	return {
+		checks,
+		concurrency: resolve_concurrency(available_cores, concurrent_runs, checks),
+		unit_worker_cap: is_unit_included
+			? resolve_unit_worker_cap(available_cores, concurrent_runs)
+			: undefined,
+	}
+}
+
+// Printed once per run, so a gate that was slow on someone else's machine can be read without
+// re-deriving the plan from their core count.
+//
+// **The two fragments come from `josh-verdict.ts` since joshuafolkken/kit#1379.** `josh time` matches
+// this line to tell where a gate run's output begins — it is the one line the gate prints before any
+// check body exists — so the printer and the detector build it from the same strings, exactly as they
+// already do for the verdict.
+// **The machine is described as shared only when it is.** A solo gate prints exactly the line it
+// always printed — which is what keeps `josh time`'s detector, and every reader used to the old
+// output, unaffected — while a narrowed one says why it is narrow, so a lane owner reading a slow
+// gate is not left deriving the reason from a worker count that looks wrong (joshuafolkken/kit#1515).
+function format_machine(available_cores: number, concurrent_runs: number): string {
+	const cores = `${String(available_cores)} cores`
+
+	if (concurrent_runs <= unit_worker_share.SOLO_RUNS) return cores
+
+	return `${cores}, ${String(concurrent_runs)} unit runs`
+}
+
+// **A gate that is not running the unit suite says so where the worker count would go.** The line is
+// what a slow or surprising gate is read against, and "3 of 3" alone would leave a reader deriving
+// which three from the check bodies below it.
+function format_unit_cap(plan: GatePlan): string {
+	if (!has_unit_check(plan.checks)) return `${UNIT_LABEL} elsewhere`
+	if (plan.unit_worker_cap === undefined) return `${UNIT_LABEL} unrestricted`
+
+	return `${UNIT_LABEL} at ${String(plan.unit_worker_cap)} workers`
+}
+
+function format_gate_plan(
+	plan: GatePlan,
+	available_cores: number = availableParallelism(),
+	concurrent_runs: number = unit_worker_share.SOLO_RUNS,
+): string {
+	const cap = format_unit_cap(plan)
+	const count = `${String(plan.concurrency)} of ${String(plan.checks.length)}`
+	const width = `${count}${josh_verdict.GATE_OPENING_MARK}`
+	const machine = format_machine(available_cores, concurrent_runs)
+
+	return `${josh_verdict.GATE_OPENING_PREFIX}${width}, ${cap} (${machine})`
+}
+
+const gate_plan = {
+	BEHAVIOR_LABEL,
+	GATE_CHECKS,
+	LINT_LABEL,
+	MEASURED_CORES,
+	RESERVED_CORES,
+	STATIC_CHECKS,
+	TYPE_CHECK_LABEL,
+	UNIT_LABEL,
+	WARNING_CHECKER_LABELS,
+	check_weight,
+	format_gate_plan,
+	format_machine,
+	format_unit_cap,
+	has_unit_check,
+	plan_of,
+	resolve_concurrency,
+	resolve_gate_plan,
+	resolve_unit_worker_cap,
+	select_gate_checks,
+}
+
+export type { GateCheck, GatePlan }
+export { gate_plan }

package/scripts/gate/gate-report.ts

@@ -0,0 +1,207 @@
+import { GATE_COMMAND } from '#scripts/josh/josh-command-types'
+import { josh_verdict } from '#scripts/josh/josh-verdict'
+import { buffered_process, type BufferedProcessResult } from '#scripts/lib/buffered-process'
+import { status_icons } from '#scripts/lib/status-icons'
+import { test_unit_guard } from '#scripts/test/test-unit-guard'
+import { gate_log } from './gate-log'
+import { gate_plan } from './gate-plan'
+
+// The gate's console reporting, split out of `verification-gate.ts` so that file stays under its line
+// ceiling while it grows the scoped pre-check and the failure summary (joshuafolkken/kit#2296). Nothing
+// about what is printed changes in the move: the four blocks, the log notice and the verdict come out
+// exactly as before, with one addition — the per-failure action lines below.
+
+const { FAIL_ICON, PASS_ICON } = status_icons
+
+interface GateStep {
+	label: string
+	command_args: ReadonlyArray<string>
+}
+
+interface GateStepResult extends BufferedProcessResult {
+	label: string
+	// What was actually run. The type check's command is resolved per project, so a failure on the
+	// `check` step is only reproducible if the header names the command rather than the label.
+	command: string
+}
+
+function is_gate_step_failed(result: GateStepResult): boolean {
+	return buffered_process.is_process_failed(result)
+}
+
+// A passing check's output is not read. What a green gate has to say is "all four passed", and
+// `print_gate_summary` already says it in one line — while the four bodies, vitest's per-file
+// listing among them, run to tens of kilobytes that then sit in the conversation and are re-read on
+// every later turn. The gate runs more than once per Issue, so the cost is per run, not per Issue
+// (joshuafolkken/kit#967).
+//
+// A failing check keeps its whole output: that is the one time the body is the answer. So does a
+// check that **passed without running** — `test-unit-guard` exits 0 with a notice when vitest is
+// absent, and suppressing that made a gate which ran zero tests print the same five lines as one
+// that ran them all. The marker comes from the guard itself rather than being matched by eye, so
+// the two cannot drift apart.
+function is_skip_notice(result: GateStepResult): boolean {
+	return result.output.includes(test_unit_guard.SKIP_MARKER)
+}
+
+// A check can exit 0 and still have something to say: `lint-parallel` runs eslint without
+// `--max-warnings 0`, and svelte-check reports warnings the same way. Suppressing those would let a
+// gate report "passed" with the warnings invisible, which is the same failure as hiding a skip.
+//
+// Unlike the skip marker this *is* a heuristic — the words come from third-party tools, so there is
+// no constant to share with them. It is deliberately loose: a false positive costs one printed body,
+// a false negative hides a warning, and only one of those is worth avoiding.
+const WARNING_MARKERS: ReadonlyArray<string> = ['warning', 'Warning', '⚠']
+
+function has_warnings(result: GateStepResult): boolean {
+	return WARNING_MARKERS.some((marker) => result.output.includes(marker))
+}
+
+// The withholding path's counterpart to `has_warnings`, and deliberately narrower than it
+// (joshuafolkken/kit#2318). `has_warnings` is read by `should_print_body`, where a false positive
+// costs one printed body — the loose match above is right there. `record_green_gate` reads *this*
+// one, where a false positive is not one printed line but the whole green record withheld, which
+// turns a green gate's `run:review --join` red. So the record is withheld only for a warning from a
+// checker that actually emits per-tree warnings (`WARNING_CHECKER_LABELS`), never for a benign line
+// from another tool that happens to contain the word — a Vite config deprecation on `test:unit` was
+// the line that stopped a green gate's commit chain.
+//
+// **The safe-chain shim's banner is not the checker's either** (joshuafolkken/kit#2447). Where
+// `setup-ci` installed the shims but the binary cannot be reached, every `pnpm` a check spawns prints
+// "Warning: safe-chain is not available …" into that check's output, so a green lint withheld the
+// record on every CI run. The banner's lines are dropped before the match; a real warning on any
+// other line still withholds.
+const SAFE_CHAIN_BANNER = 'safe-chain is not available'
+
+function has_checker_warning(result: GateStepResult): boolean {
+	if (!gate_plan.WARNING_CHECKER_LABELS.includes(result.label)) return false
+
+	return result.output
+		.split('\n')
+		.some(
+			(line) =>
+				!line.includes(SAFE_CHAIN_BANNER) &&
+				WARNING_MARKERS.some((marker) => line.includes(marker)),
+		)
+}
+
+function should_print_body(result: GateStepResult, is_verbose: boolean): boolean {
+	if (is_verbose || is_gate_step_failed(result)) return true
+
+	return is_skip_notice(result) || has_warnings(result)
+}
+
+// Seconds to one decimal, which is the resolution the answer is read at: the question a gate's
+// timing answers is "which of the four is the long pole", and no check is ever separated from
+// another by less than a tenth of a second (joshuafolkken/kit#1248).
+const MS_PER_SECOND = 1000
+const SECONDS_DECIMALS = 1
+
+function format_seconds(elapsed_ms: number): string {
+	return `${(elapsed_ms / MS_PER_SECOND).toFixed(SECONDS_DECIMALS)}s`
+}
+
+// The duration goes at the **end** of the header, after the command. The header's first job is
+// naming the one command to re-run while fixing (`docs/josh-commands.md` → `josh gate`), and a
+// number spliced in front of it would push that name out of the place a reader scans for it.
+//
+// Built rather than inlined because the log file names each section with the same string
+// (joshuafolkken/kit#1227): a header written twice is a header the two copies can disagree about,
+// and the log exists precisely to be read when the console's copy has been elided.
+function gate_step_header(result: GateStepResult): string {
+	const icon = is_gate_step_failed(result) ? FAIL_ICON : PASS_ICON
+
+	return `${icon} ${result.label} (pnpm ${result.command}) ${format_seconds(result.elapsed_ms)}`
+}
+
+function print_gate_step(result: GateStepResult, is_verbose: boolean): void {
+	process.stdout.write(`\n${gate_step_header(result)}\n`)
+
+	if (should_print_body(result, is_verbose) && result.output) {
+		process.stdout.write(`${result.output}\n`)
+	}
+}
+
+// **One line per failed check, naming the command that reproduces it, printed at the tail just above
+// the verdict** (joshuafolkken/kit#2296). A red gate used to report every failing check only in its
+// bodies, which is where truncation lands: the run picked one failure at a time across separate gate
+// runs because it could not read the rest. The verdict names *which* checks failed; this names *what
+// to run* for each, and it sits in the same tail window the verdict and the log notice already
+// occupy, so a `tail -40` keeps it. The verdict stays the last line for the reason `josh-verdict.ts`
+// gives.
+function format_failure_actions(failed: ReadonlyArray<GateStepResult>): string {
+	if (failed.length === 0) return ''
+
+	const lines = failed.map(
+		(result) => `  ${FAIL_ICON} ${result.label} — re-run: pnpm ${result.command}`,
+	)
+
+	return `${GATE_COMMAND} — next:\n${lines.join('\n')}\n`
+}
+
+// The total is wall-clock for the whole command, not the sum of the four — they run concurrently,
+// so a sum would report about three times what the caller waited.
+//
+// The failure actions and the log path are printed with the summary and immediately **above** the
+// verdict line, which stays last for the reason `josh-verdict.ts` gives (joshuafolkken/kit#1227).
+function print_gate_summary(
+	failed: ReadonlyArray<GateStepResult>,
+	elapsed_ms: number,
+	step_count: string,
+	log_path?: string,
+): void {
+	const total = format_seconds(elapsed_ms)
+	const verdict =
+		failed.length === 0
+			? josh_verdict.format_gate_passed(step_count, total)
+			: josh_verdict.format_gate_failed(failed.map((result) => result.label).join(', '), total)
+
+	process.stdout.write(
+		`\n${format_failure_actions(failed)}${gate_log.format_log_notice(log_path)}${verdict}\n`,
+	)
+}
+
+interface GateReport {
+	is_verbose: boolean
+	log_path: string | undefined
+	elapsed_ms: number
+	step_count: string
+}
+
+// Everything a finished run says, in the order a reader meets it: the four blocks, then the log the
+// blocks may have been elided out of, then the failure actions and the verdict. **Every check's whole
+// output goes into the log, the ones the console dropped included** (joshuafolkken/kit#967).
+function report_gate_steps(
+	results: ReadonlyArray<GateStepResult>,
+	report: GateReport,
+): ReadonlyArray<string> {
+	for (const result of results) print_gate_step(result, report.is_verbose)
+
+	const entries = results.map((result) => ({
+		header: gate_step_header(result),
+		output: result.output,
+	}))
+	const failed = results.filter((result) => is_gate_step_failed(result))
+	const written_log = gate_log.write_gate_log(entries, report.log_path)
+
+	print_gate_summary(failed, report.elapsed_ms, report.step_count, written_log)
+
+	return failed.map((result) => result.label)
+}
+
+const gate_report = {
+	format_failure_actions,
+	format_seconds,
+	gate_step_header,
+	has_checker_warning,
+	has_warnings,
+	is_gate_step_failed,
+	is_skip_notice,
+	print_gate_step,
+	print_gate_summary,
+	report_gate_steps,
+	should_print_body,
+}
+
+export type { GateReport, GateStep, GateStepResult }
+export { gate_report }