@joshuafolkken/kit 1.2114.0 → 1.3000.0

package/scripts/test/unit-update-arguments.ts

@@ -0,0 +1,73 @@
+import type { SnapshotUpdateState } from 'vitest'
+
+// vitest's `-u` / `--update` takes an optional value (`argument: "[type]"` in its CLI definition), so
+// the bare word after it is read as the update type, never as a file filter: `josh test:unit -u
+// run-transcript` ran the whole suite (joshuafolkken/kit#5383). A word that is no update type is
+// therefore moved in front of the flag, where vitest reads it as the filter it was meant to be.
+//
+// **The keys are written here because vitest exports the accepted types only as the
+// `SnapshotUpdateState` type**, with no runtime list; the `Record` makes the compiler refuse a key
+// vitest drops or a type it adds. `true` / `false` are the boolean the option's description accepts.
+const UPDATE_VALUES: Record<SnapshotUpdateState | `${boolean}`, true> = {
+	all: true,
+	new: true,
+	none: true,
+	true: true,
+	false: true,
+}
+const UPDATE_FLAGS: ReadonlySet<string> = new Set(['-u', '--update'])
+const OPTION_PREFIX = '-'
+const NOT_FOUND = -1
+
+interface UpdateReorder {
+	arguments: ReadonlyArray<string>
+	filter?: string
+}
+
+function is_filter_word(value: string | undefined): value is string {
+	if (value === undefined || value.startsWith(OPTION_PREFIX)) return false
+
+	return !Object.hasOwn(UPDATE_VALUES, value)
+}
+
+function filter_words(vitest_arguments: ReadonlyArray<string>): ReadonlyArray<string> {
+	const next_option = vitest_arguments.findIndex((argument) => argument.startsWith(OPTION_PREFIX))
+
+	return next_option === NOT_FOUND ? vitest_arguments : vitest_arguments.slice(0, next_option)
+}
+
+function filter_flag(vitest_arguments: ReadonlyArray<string>): number {
+	const delimiter = vitest_arguments.indexOf('--')
+	const options = delimiter === NOT_FOUND ? vitest_arguments : vitest_arguments.slice(0, delimiter)
+
+	return options.findIndex(
+		(argument, index) => UPDATE_FLAGS.has(argument) && is_filter_word(options[index + 1]),
+	)
+}
+
+function reorder(vitest_arguments: ReadonlyArray<string>): UpdateReorder {
+	const flag_index = filter_flag(vitest_arguments)
+	const value = flag_index === NOT_FOUND ? undefined : vitest_arguments[flag_index + 1]
+
+	if (!is_filter_word(value)) return { arguments: vitest_arguments }
+
+	const filters = filter_words(vitest_arguments.slice(flag_index + 1))
+	const ordered = vitest_arguments.toSpliced(flag_index + 1, filters.length)
+
+	return {
+		arguments: reorder(ordered.toSpliced(flag_index, 0, ...filters)).arguments,
+		filter: value,
+	}
+}
+
+function notice(filter: string): string {
+	return `moved "${filter}" in front of the update flag — vitest reads the word after it as the update type, not a file filter.`
+}
+
+const unit_update_arguments = {
+	notice,
+	reorder,
+}
+
+export type { UpdateReorder }
+export { unit_update_arguments }

package/scripts/test/unit-worker-share.ts

@@ -1,5 +1,6 @@
 import { availableParallelism } from 'node:os'
 import { stamp_file } from '#scripts/josh/stamp-file'
+import { unit_lane_count } from './unit-lane-count'
 import { unit_run_marker } from './unit-run-marker'
 
 // How wide one vitest run may fan out when it is not the only one on the machine.
@@ -8,13 +9,9 @@ import { unit_run_marker } from './unit-run-marker'
 // `josh gate` at once each concluded "11 cores, take 7 workers" and put 42 workers on 11 cores. The
 // pre-push hook once passed no cap at all; it now runs the suite through `test_unit_guard.run_guarded_unit`,
 // the same guard `josh test:unit` uses, so the share below applies there too.
-// Measured on the machine this was found on — load average 14.97 in the field, and 209 in a deliberate
-// reproduction of six concurrent suites, against 22 once the share below was applied.
 //
-// **What it fixes, and what it does not.** Six concurrent copies of the full suite produced ten
-// `Test timed out in 10000ms` failures across six runs; at the share this module hands out, the same
-// six runs produced **none**. It is the *second* multiplicand of those timeouts — the first
-// was a live `git fetch` inside two test files, which is fixed in `test-network-guard.ts` and its
+// **Concurrent suites need a share to avoid oversubscription** (joshuafolkken/kit#1515, which records
+// the load averages). Oversubscription compounds timeouts; the other cause of those timeouts was a live `git fetch` inside two test files, which is fixed in `test-network-guard.ts` and its
 // callers, and which no worker count would have repaired: that one failed on an idle machine at one
 // worker.
 //
@@ -26,8 +23,14 @@ import { unit_run_marker } from './unit-run-marker'
 // **The run markers and their division of the machine are `unit-run-marker.ts`**, the part the vitest
 // config imports (joshuafolkken/kit#4572); the capacity and claim bounds and the flag handling are here.
 const { MIN_WORKERS, NESTED_KEY, NESTED_VALUE, SOLO_RUNS } = unit_run_marker
-const { is_nested_run, live_run_count, mark_run_started, marker_path, resolve_unit_workers } =
-	unit_run_marker
+const {
+	is_nested_run,
+	live_run_count,
+	mark_run_started,
+	marker_path,
+	resolve_unit_workers,
+	sharing_runs,
+} = unit_run_marker
 
 // Vitest's own flag, in both spellings its CLI accepts — it normalizes `--max-workers` to the same
 // option, so a run that recognized only one of them would replace a number the caller typed with the
@@ -98,20 +101,31 @@ function cap_to_claim(share: number | undefined, claim: UnitClaim | undefined):
 	return Math.min(share ?? bound, bound)
 }
 
-// The share this run may take, read from the machine. Separate from `resolve_unit_workers` so that
-// one stays a pure function of two numbers and every test of it can pass them.
-//
 // **A nested run is already counted, and adding one for it would be wrong rather than cautious.**
 // Inside `josh gate` the marker was written by the parent before this process started, so `+ 1` here
 // would count one run twice — and on a machine the gate leaves uncapped, a four-core CI runner among
 // them, that alone would halve a solo run nothing was sharing.
+function own_run(): number {
+	return is_nested_run() ? 0 : SOLO_RUNS
+}
+
+// The share this run may take, read from the machine. Separate from `resolve_unit_workers` so that
+// one stays a pure function of two numbers and every test of it can pass them.
+//
+// **`live_lanes` defaults to this lane alone rather than to a reading** (joshuafolkken/kit#6682), so a
+// caller that does not pass the lanes keeps dividing by the runs only. The share `test-unit-guard.ts`
+// opens and the claim `gate-plan.ts` declares both pass `live_lane_count()`, so the ledger holds what
+// the run uses.
 function current_share(
 	available_cores: number = availableParallelism(),
 	live_runs: number = live_run_count(),
 	free: FreeCapacity = UNREAD_CAPACITY,
+	live_lanes: number = SOLO_RUNS,
 ): number | undefined {
-	const own_run = is_nested_run() ? 0 : SOLO_RUNS
-	const share = resolve_unit_workers(available_cores, live_runs + own_run)
+	const share = resolve_unit_workers(
+		available_cores,
+		sharing_runs(live_runs + own_run(), live_lanes),
+	)
 
 	return cap_to_capacity(share, free, available_cores)
 }
@@ -164,6 +178,7 @@ async function with_run_marker<T>(run: () => Promise<T>): Promise<T> {
 
 const unit_worker_share = {
 	...unit_run_marker,
+	...unit_lane_count,
 	MAIN_PROCESS_CORES,
 	cap_to_capacity,
 	cap_to_claim,

package/scripts/test/whole-suite-files.ts

@@ -28,6 +28,7 @@ const ROOT_FILES: ReadonlyArray<string> = [
 // whole suite on any of these with no word of why. Named here, they print the reason instead.
 // `whole-suite-files.test.ts` holds the list to both graphs, so an import added to either fails there.
 const IMPORTED_BY_EVERY_TEST: ReadonlyArray<string> = [
+	'scripts/agent/agent-headless.ts',
 	'scripts/git/constants.ts',
 	'scripts/git/git-location-environment.ts',
 	'scripts/init/init-paths.ts',
@@ -41,6 +42,7 @@ const IMPORTED_BY_EVERY_TEST: ReadonlyArray<string> = [
 	'scripts/lib/json-value.ts',
 	'scripts/lib/read-file.ts',
 	'scripts/lib/timeouts.ts',
+	'scripts/run/run-headless-keys.ts',
 	'scripts/test/unit-durations.ts',
 	'scripts/test/unit-run-marker.ts',
 	'scripts/test/unit-setup-files.ts',

package/scripts/time-runtime/guard-rephrase.ts

@@ -0,0 +1,66 @@
+import type { Block, TranscriptLine } from './time-transcript-line'
+
+// Guard refusals rephrased into an allowed call — the false-positive proxy of a guard's predicate,
+// read by guard-friction's `GuardRow.rephrased` and by `josh rule:value` (`rule-rephrase.ts`).
+//
+// **A refusal is rephrased when the next call of the same tool, issued after the refusal came back,
+// is allowed.** A call issued beside the refused one in the same parallel turn is not its rephrasing,
+// so only a tool_use read after the refusal's result is a candidate; a candidate refused again waits
+// for the next call in turn. The guard is the raw label the block carries — each caller maps a renamed
+// guard to its current name.
+
+interface RephraseState {
+	names: Map<string, string>
+	pending: Map<string, string>
+	candidates: Map<string, string>
+	rephrased: Array<string>
+}
+
+function on_use(state: RephraseState, block: Block): void {
+	const guard = state.pending.get(block.name)
+
+	state.names.set(block.id, block.name)
+	if (guard === undefined) return
+	state.candidates.set(block.id, guard)
+	state.pending.delete(block.name)
+}
+
+function on_allowed(state: RephraseState, id: string): void {
+	const guard = state.candidates.get(id)
+
+	if (guard !== undefined) state.rephrased.push(guard)
+}
+
+function on_result(state: RephraseState, block: Block): void {
+	const name = state.names.get(block.result_id) ?? ''
+
+	if (block.refusal_guard === '') {
+		on_allowed(state, block.result_id)
+	} else {
+		state.pending.set(name, block.refusal_guard)
+	}
+}
+
+function on_block(state: RephraseState, block: Block): void {
+	if (block.type === 'tool_use') on_use(state, block)
+	else if (block.result_id !== '') on_result(state, block)
+}
+
+// The guard of every refusal in the session that the next call of its tool rephrased, in order.
+function rephrased_guards(lines: ReadonlyArray<TranscriptLine>): Array<string> {
+	const state: RephraseState = {
+		names: new Map(),
+		pending: new Map(),
+		candidates: new Map(),
+		rephrased: [],
+	}
+	const blocks = lines.flatMap((line) => line.blocks)
+
+	for (const block of blocks) on_block(state, block)
+
+	return state.rephrased
+}
+
+const guard_rephrase = { rephrased_guards }
+
+export { guard_rephrase }

package/scripts/time-runtime/time-agent-bundles.ts

@@ -16,11 +16,11 @@ import { time_spans, type Span } from './time-spans'
 // than a second copy of that arithmetic living here. The two series then fold in identically, which is
 // what keeps `unattributed_round_trips` at zero.
 //
-// **What the shape costs.** Run #1839 launched three investigation subagents at 1.7 / 7.3 / 11.4
-// minutes, in three separate turns, whose three questions — the lane machinery, the API signatures,
-// the registry and log paths — needed nothing from one another and could have gone out at once. The
-// consecutive detector counted none of them. The three review finders it launched at 36.7 minutes, by
-// contrast, went out *in one turn* and cost nothing, which is the shape this series must not charge.
+// **What the shape costs.** Run #1839 launched three investigation subagents in three separate
+// turns, whose three questions — the lane machinery, the API signatures, the registry and log
+// paths — needed nothing from one another and could have gone out at once. The consecutive detector
+// counted none of them. The three review finders it launched later, by contrast, went out *in one
+// turn* and cost nothing, which is the shape this series must not charge.
 //
 // ## When two launches could have been one
 //

package/scripts/time-runtime/time-bundle-call.ts

@@ -200,8 +200,8 @@ const READ_JOSH_SUBCOMMANDS: ReadonlySet<string> = new Set([
 ])
 
 // The launchers that put a `josh` subcommand on the line, and the word that names it. `pnpm josh`,
-// `npx josh` and the bare `josh` name it as the word `josh`; `tsx scripts/josh/josh.ts` names it as a
-// path ending in `josh.ts`. The subcommand is the token after whichever the scan finds first.
+// `npx josh` and the bare `josh` name it as the word `josh`; `node --import tsx scripts/josh/josh.ts`
+// (or `tsx scripts/josh/josh.ts`) names it as a path ending in `josh.ts`. The subcommand is the token after whichever the scan finds first.
 const JOSH_WORD = 'josh'
 const JOSH_SCRIPT_SUFFIX = 'josh.ts'
 

package/scripts/time-runtime/time-bundles.ts

@@ -160,8 +160,8 @@ function shares_target(left: ReadonlyArray<string>, right: ReadonlyArray<string>
 // what kept the guard silent for a whole run. `extend` below does not merely decline to count such a
 // pair: it *flushes* the sequence and restarts it at the conflicting call, so a stretch of single-call
 // turns all editing one file could never take `sequence.length` past 1, and the refusal at
-// `time-batch-guard.ts` — which needs 2 — could never fire however long the stretch ran. Measured on
-// `fullrun #1503`: 17 such stretches, 108 seconds, and zero refusals in two hours.
+// `time-batch-guard.ts` — which needs 2 — could never fire however long the stretch ran
+// (`fullrun #1503`).
 //
 // **Read-after-read keeps the old reading deliberately.** Two reads of one file can genuinely depend
 // — a `grep` that finds a line number and a `sed -n` that prints around it — so the proxy still earns

package/scripts/time-runtime/time-command-key.ts

@@ -2,11 +2,8 @@ import { time_spans, type Span } from './time-spans'
 
 // What counts as *the same command* across a run's spans.
 //
-// Two questions need it and used to answer it separately: the failure chain asks whether a call
-// repeats one that just failed, and the per-invocation listing asks which calls belong on one row.
-// Both mean the same thing by "the same command", so the rule sits here rather than in either of
-// them — a second copy is the clone `CLAUDE.md` prohibits, in the one place a drift would make the
-// rework figure and the per-invocation row disagree about which calls were the same command.
+// The failure chain and per-invocation listing need the same command identity so repeat detection
+// and row grouping agree. Sharing that definition prevents their rework figures from drifting.
 //
 // **The josh subcommand wins where there is one.** `Bash: pnpm` alone would put `josh gate` and
 // `josh lint` under one key, so the second would be read as a repeat of the first.

package/scripts/time-runtime/time-density-hook.ts

@@ -1,10 +1,10 @@
-import { closeSync, fstatSync, openSync, readSync } from 'node:fs'
 import { stamp_file } from '#scripts/josh/stamp-file'
 import { json_value } from '#scripts/lib/json-value'
 import { z } from 'zod'
 import { time_batch_guard, type GuardedCall } from './time-batch-guard'
 import { time_density } from './time-density'
 import { time_hook_transcript } from './time-hook-transcript'
+import { transcript_tail } from './transcript-tail'
 
 // The disk half of the live density line: find the transcript, read enough
 // of it, and remember when the line was last emitted.
@@ -28,12 +28,6 @@ import { time_hook_transcript } from './time-hook-transcript'
 // there too: `time_density.last_turn_calls` withholds the count when the tail's final line does not
 // parse, because that line belongs to the turn the count is about.
 
-// How much of the transcript's end is read. The file grows to several megabytes over a long run —
-// 4.7 MB and 2,712 lines for the largest in this checkout — and reading all of it on every edit would
-// put the run's own history in front of every write. A quarter of a megabyte is far more than the ten
-// round trips the reading needs and is read in a couple of milliseconds.
-const TAIL_BYTES = 262_144
-const FILE_START = 0
 // **One record per session, keyed on the transcript the payload named**, rather than per checkout the
 // way `josh gate`'s stamp is. What is being throttled is a *run*, and a run is one session: keyed on
 // the checkout, a session started — or cleared — within the interval of the previous one's line would
@@ -84,28 +78,6 @@ function parse_call(raw_payload: string): GuardedCall | undefined {
 	return { name: call.tool_name, input: call.tool_input }
 }
 
-// The last `max_bytes` of a file, as text. The leading line is usually cut mid-way, which every
-// reader below already handles: an unparseable line is dropped rather than dated.
-//
-// **Only the bytes `readSync` reports are decoded.** `Buffer.alloc` zero-fills, and a short read — a
-// real possibility on the network- and FUSE-backed home directories these transcripts can live on —
-// would otherwise leave NUL padding on the end of the text, making the *last* line unparseable. That
-// is the one line the turn's call count is read from.
-function read_tail(file_path: string, max_bytes: number = TAIL_BYTES): string {
-	const descriptor = openSync(file_path, 'r')
-
-	try {
-		const { size } = fstatSync(descriptor)
-		const length = Math.min(size, max_bytes)
-		const buffer = Buffer.alloc(length)
-		const read = readSync(descriptor, buffer, FILE_START, length, size - length)
-
-		return buffer.subarray(FILE_START, read).toString('utf8')
-	} finally {
-		closeSync(descriptor)
-	}
-}
-
 function notice_path(transcript_path: string): string {
 	return stamp_file.stamp_path(NOTICE_PREFIX, transcript_path)
 }
@@ -145,7 +117,7 @@ function notice_for(raw_payload: string, now_ms: number): string | undefined {
 
 	if (transcript_path === undefined) return undefined
 
-	const tail = read_tail(transcript_path)
+	const tail = transcript_tail.read_tail(transcript_path)
 	const reading = time_density.read_window(tail)
 	const target = notice_path(transcript_path)
 
@@ -175,7 +147,6 @@ const time_density_hook = {
 	notice_path,
 	parse_call,
 	parse_transcript_path,
-	read_tail,
 }
 
 export { time_density_hook }

package/scripts/time-runtime/time-format.ts

@@ -19,8 +19,8 @@ import { MS_PER_SECOND } from '#scripts/lib/timeouts'
 
 const SECOND_DECIMALS = 1
 const LABEL_WIDTH = 24
-// Wide enough for a three-digit run (`335.4 min`), so a long session's rows stay in column with a
-// short one's rather than pushing the share out by a character.
+// Wide enough for a three-digit minute count with its decimal and unit, so a long session's rows
+// stay in column with a short one's rather than pushing the share out by a character.
 const MINUTES_WIDTH = 9
 // The answer a table gives where the half it sums was never read at all, kept apart from the phase
 // table's `not detected` because the two ask different questions: a phase is about a marker, this is
@@ -52,8 +52,8 @@ function overflow_line(row_count: number): Array<string> {
 	]
 }
 
-// Seconds rather than minutes for a per-turn figure: one turn is tens of seconds, and `0.1 min` is
-// too coarse to show the rise across a batch that this scale exists to make visible.
+// Seconds rather than minutes for a per-turn figure: one turn is tens of seconds, and a tenth of a
+// minute is too coarse to show the rise across a batch that this scale exists to make visible.
 function format_seconds(duration_ms: number): string {
 	return `${(duration_ms / MS_PER_SECOND).toFixed(SECOND_DECIMALS)} s`
 }

package/scripts/time-runtime/time-josh-names.ts

@@ -0,0 +1,51 @@
+import { canonical_command } from '#scripts/josh/josh-aliases'
+import { time_shell } from '#scripts/time-runtime/time-shell'
+
+// The josh names `time_shell` reads, alias-expanded — the one layer that expands them, and the one a
+// reader that matches a name against canonical ones goes through (joshuafolkken/kit#6161). `time_shell`
+// returns the names as typed, so it does not import `josh-aliases.ts` (joshuafolkken/kit#6159).
+//
+// **An alias is expanded, so one command is one name.** Every reading keyed on the raw name took
+// `pnpm josh ga` and `pnpm josh gate` as two different commands: the per-command table printed them
+// as two rows, the per-invocation table dropped both for having one call each, and — the one with
+// real cost — the failure chain did not see the second as answering the first, so the time a red gate
+// made the run pay again went unreported.
+//
+// **The expansion belongs at the name, not at each reader.** A gate-run reader had once patched its
+// own copy of this reading, which left the gate count and the per-invocation table answering
+// differently about the same run; `canonical_command` here is the one rule every reader goes through.
+
+// `josh <name>` or `josh <name> <arguments>…` with the subcommand expanded; the arguments are kept
+// verbatim, and `''` (a segment that runs no josh command) stays `''`.
+function canonical_name(name: string): string {
+	if (name === '') return ''
+
+	const [subcommand = '', ...rest] = name.slice(time_shell.JOSH_PREFIX.length).split(' ')
+
+	return [`${time_shell.JOSH_PREFIX}${canonical_command(subcommand)}`, ...rest].join(' ')
+}
+
+function josh_command_of(command: string): string {
+	return canonical_name(time_shell.josh_command_of(command))
+}
+
+function josh_command_of_segment(segment: string): string {
+	return canonical_name(time_shell.josh_command_of_segment(segment))
+}
+
+function josh_commands_of(command: string): Array<string> {
+	return time_shell.josh_commands_of(command).map((name) => canonical_name(name))
+}
+
+function josh_signatures_of(command: string): Array<string> {
+	return time_shell.josh_signatures_of(command).map((signature) => canonical_name(signature))
+}
+
+const time_josh_names = {
+	josh_command_of,
+	josh_command_of_segment,
+	josh_commands_of,
+	josh_signatures_of,
+}
+
+export { time_josh_names }

package/scripts/time-runtime/time-markers.ts

@@ -7,7 +7,7 @@ import { json_value } from '#scripts/lib/json-value'
 // A stage is bounded by things a transcript can be read for, so this module is the one rule for what
 // counts as a boundary — and it is deliberately about **recognizable commands, never durations**: a
 // boundary guessed from "this interval looks like a review" would move whenever a run got faster,
-// which is the one thing a measurement used to compare two runs must not do.
+// which would make comparisons between runs unreliable.
 //
 // **Only the boundaries `josh_command` cannot already express live here.** `gate`, `pr` and `merge`
 // are `pnpm josh <cmd>` invocations that `time-spans.ts` already names, and re-detecting them here
@@ -27,9 +27,9 @@ import { json_value } from '#scripts/lib/json-value'
 // the fork's own transcript, where it returns instantly (it only loads the skill text). The review's
 // real wall clock is the fork's own `Read`/`grep` spans. Those spans carry no marker of their own, so
 // they inherit the marker of the parent span they run inside — the `Agent` call (`time-overlap.ts`).
-// Left unmarked that parent deletes the phase rather than moving it, leaving a ~0 ms `review`. So the
-// `Agent` launch is marked here, and the `Skill(code-review)` marker stays for older transcripts in
-// which the main line loaded the skill itself.
+// Left unmarked that parent deletes the phase rather than moving it, leaving an empty `review`. So
+// the `Agent` launch is marked here, and the `Skill(code-review)` marker stays for older
+// transcripts in which the main line loaded the skill itself.
 //
 // **The launch is recognized by its prompt carrying both `/code-review` and `review:attest`.** The
 // first is the instruction to invoke the review skill; the second is the attestation step the launch

package/scripts/time-runtime/time-phase-names.ts

@@ -71,7 +71,7 @@ const PHASE_ORDER: ReadonlyArray<PhaseName> = [
 // transcript was read at all, rather than on a marker.
 //
 // **They are withheld on exactly the terms the three transcript category rows are**
-// — no span read at all. `wait` printing `0.0 min` where nothing was read
+// — no span read at all. `wait` printing a zero where nothing was read
 // asserts that nobody waited, and the run that produces it is the one a reader is least able to check.
 // Keying every one of them off the same criterion is also what keeps `wait` + `wait-outside` equal to
 // the `human wait` category row: they are withheld together or printed together, never some of each.
@@ -79,7 +79,7 @@ const PHASE_ORDER: ReadonlyArray<PhaseName> = [
 // **`wait-outside` is in this set rather than detected on the run's edges**,
 // which is where it differs from `pre-run` and `post-run`. Its zero is not a claim about an unchecked
 // half, because those two rows report the same two boundaries in their own right — a reader seeing
-// `pre-run  not detected` beside `wait-outside  0.0 min` already knows that edge was never found, and
+// `pre-run  not detected` beside a zero `wait-outside` already knows that edge was never found, and
 // a third row saying so would restate it at the price of the invariant above.
 const SPAN_BACKED_PHASES: ReadonlySet<PhaseName> = new Set([
 	WAIT_PHASE,

package/scripts/time-runtime/time-shell.ts

@@ -1,5 +1,4 @@
 import { cost_blocks } from '#scripts/cost-runtime/cost-blocks'
-import { canonical_command } from '#scripts/josh/josh-aliases'
 import { json_value } from '#scripts/lib/json-value'
 
 // Reading a shell command well enough to name what it ran.
@@ -15,10 +14,9 @@ import { json_value } from '#scripts/lib/json-value'
 // session and says nothing: `git`, `gh` and `pnpm` are different work with different costs.
 //
 // **The first word is not always the command.** Most calls here open with `cd <path> &&`, and taking
-// the literal first word put `Bash: cd` at the top of every table — 82 calls and 12.1 minutes of one
-// measured session, naming the one part of the command that did no work. So the chain is split into
-// segments and each segment walked past its leading `VAR=…` assignments and its wrappers, to the
-// first word that is a command.
+// the literal first word put `Bash: cd` at the top of every table, naming the one part of the
+// command that did no work. So the chain is split into segments and each segment walked past its
+// leading `VAR=…` assignments and its wrappers, to the first word that is a command.
 //
 // **A prefix is skipped word by word, not segment by segment.** Reading only each segment's first
 // word left `FOO=1 pnpm test` reported as `Bash: FOO=1` and `time pnpm build` as `Bash: time` — the
@@ -122,7 +120,10 @@ const FLAG_AND_VALUE = 2
 // charged `git commit -m "ran pnpm josh gate"` to `josh gate`, and this repository's own commit
 // messages and issue comments name josh subcommands constantly. Only the first match counts: a
 // compound command naming two would otherwise charge its whole duration to each.
-const JOSH_PATTERN = /^(?:(?:pnpm|npx)\s+(?:exec\s+)?)?josh\s+([a-z][\w:-]*)/u
+const JOSH_LAUNCHER = String.raw`^(?:(?:pnpm|npx)\s+(?:exec\s+)?)?josh`
+const JOSH_PATTERN = new RegExp(String.raw`${JOSH_LAUNCHER}\s+([a-z][\w:-]*)`, 'u')
+// A josh call with or without a subcommand — `pnpm josh`, `josh --help` (joshuafolkken/kit#7137).
+const JOSH_LAUNCHER_PATTERN = new RegExp(String.raw`${JOSH_LAUNCHER}(?:\s|$)`, 'u')
 const JOSH_PREFIX = 'josh '
 const COMMAND_KEY = 'command'
 
@@ -283,6 +284,14 @@ function blanked(command: string): string | undefined {
 	return command.replaceAll(QUOTED_SPAN_PATTERN, (span) => ' '.repeat(span.length))
 }
 
+// Only the text the shell never expands is blanked — a single-quoted span and an escaped character —
+// so a `` ` `` or `$` left here is one the shell acts on, and a double-quoted span stays as written.
+function literal_blanked(command: string): string {
+	return command.replaceAll(QUOTED_SPAN_PATTERN, (span) =>
+		span.startsWith(DOUBLE_QUOTE) ? span : ' '.repeat(span.length),
+	)
+}
+
 function discarded_commands(command: string): Array<string> {
 	const plain = unquoted(command)
 
@@ -302,21 +311,20 @@ function bash_label(command: string): string {
 	return word === '' ? cost_blocks.BASH_TOOL : `${cost_blocks.BASH_TOOL}${BASH_SEPARATOR}${word}`
 }
 
-// **An alias is expanded here, so one command is one name**. Every reading
-// built on this field keyed `pnpm josh ga` and `pnpm josh gate` as two different commands: the
-// per-command table printed them as two rows, the per-invocation table dropped both for having one
-// call each, and — the one with real cost — the failure chain did not see the second as answering the
-// first, so the time a red gate made the run pay again went unreported.
+// The josh subcommand one segment runs, as typed, or `''` for a segment that runs none. Shared by the
+// two readers below so what counts as a segment's josh command is one rule, not two.
 //
-// **The expansion belongs at the name, not at each reader.** `time-gate-runs.ts` had already patched
-// its own copy of this reading, which left the gate count and the per-invocation table answering
-// differently about the same run; `canonical_command` is the one rule both now go through.
-// The josh subcommand one segment runs, alias-expanded, or `''` for a segment that runs none. Shared
-// by the two readers below so what counts as a segment's josh command is one rule, not two.
+// **An alias is not expanded here** (joshuafolkken/kit#6159): expanding pulled the alias table into
+// every reader of this file. A reader that keys or matches on the name goes through
+// `time-josh-names.ts`, the one layer that expands.
 function josh_command_of_segment(segment: string): string {
 	const name = JOSH_PATTERN.exec(command_words(segment).join(' '))?.[1]
 
-	return name === undefined ? '' : `${JOSH_PREFIX}${canonical_command(name)}`
+	return name === undefined ? '' : `${JOSH_PREFIX}${name}`
+}
+
+function runs_josh(segment: string): boolean {
+	return JOSH_LAUNCHER_PATTERN.test(command_words(segment).join(' '))
 }
 
 function josh_command_of(command: string): string {
@@ -427,14 +435,17 @@ const time_shell = {
 	bash_label,
 	blanked,
 	command_segment,
+	command_words,
 	discarded_commands,
 	has_heredoc,
 	josh_arguments,
+	runs_josh,
 	josh_command_of,
 	josh_command_of_segment,
 	josh_commands_of,
 	josh_signatures_of,
 	leading_word,
+	literal_blanked,
 	unquoted,
 	without_heredoc_bodies,
 }

package/scripts/time-runtime/time-single-check.ts

@@ -2,10 +2,10 @@ import { time_shell } from './time-shell'
 
 // Which calls are one verification check run on its own, and what makes two of them the same call.
 //
-// Measured on run #1379, that run issued eight of these — 45.9 seconds of tool time, six of them in
-// the fix phase, each its own round trip — and 18.1 seconds after the last one `josh gate` ran lint,
-// the type check, the spell check and the unit tests over the same tree. Three repeated an earlier
-// call **with the same arguments**, and every one of those three followed an edit.
+// Run #1379 issued eight of these — six of them in the fix phase, each its own round trip — and
+// shortly after the last one `josh gate` ran lint, the type check, the spell check and the unit
+// tests over the same tree. Three repeated an earlier call **with the same arguments**, and every
+// one of those three followed an edit.
 //
 // **The arguments are part of the identity, and that is the whole reason this module exists.**
 // `time-command-key.ts` keys a call by its josh subcommand, because a span keeps no input — which is