@joshuafolkken/kit 1.872.0

package/scripts/delegation/delegation-policy.ts

@@ -0,0 +1,178 @@
+// Which steps of a run may be delegated to a cheaper execution tier (joshuafolkken/kit#969).
+//
+// **The decision takes no judgement.** "This one is simple enough" is a judgement made under cost
+// pressure, and cost pressure resolves it toward "simple enough" exactly when a mistake is most
+// likely to be shipped — the same reason `josh review:level` decides the review depth from the
+// changed paths rather than from how big the change feels.
+//
+// So the list is an enumeration and **anything not on it is kept**. A step nobody thought about
+// lands on the expensive side, which is the direction that costs money rather than correctness.
+
+type DelegationVerdict = 'delegate' | 'keep'
+
+const DELEGATE_VERDICT: DelegationVerdict = 'delegate'
+const KEEP_VERDICT: DelegationVerdict = 'keep'
+
+interface DelegatableStep {
+	name: string
+	// What the cheaper tier is asked to do.
+	does: string
+	// **The reason it may be delegated at all.** A step is delegatable only when a wrong result is
+	// *caught*, not merely unlikely — and caught by something that runs in the parent tier and costs
+	// less than redoing the step. Without that, a quiet mistake ships.
+	verifier: string
+}
+
+// Where the pre-implementation reading stops being cheaper in the main line (joshuafolkken/kit#1426).
+//
+// **A count, not a forecast.** The reads are counted as they are made rather than predicted before
+// the investigation starts, so nothing here rests on guessing how large it will be. Two files the run
+// will not edit stay in the main line, because delegating costs two extra main-line turns — one to
+// write the brief, one to read the result, about 18 seconds at run #1406's measured 8.8 s of model
+// wait per turn — and below the threshold that round trip costs more than carrying the text.
+const INVESTIGATION_FILE_THRESHOLD = 3
+
+// The enumeration. Short on purpose: every entry had to name a verifier, and most candidates could
+// not (below).
+const DELEGATABLE_STEPS: ReadonlyArray<DelegatableStep> = [
+	{
+		name: 'gate-fix',
+		does: 'apply the fixes the verification gate already named — a lint rule, a type error, a spelling the dictionary rejects',
+		verifier:
+			'`pnpm josh gate` is re-run; a wrong fix fails it again, and the failure names the file',
+	},
+	{
+		name: 'epic-child',
+		// One row, two entry points: an epic's child under `epicrun` and one named issue of a
+		// `backlogrun` are the same unit — same brief, same summary, same verifier
+		// (joshuafolkken/kit#1149, folded from `queue` into `backlogrun` by joshuafolkken/kit#1984). A
+		// second row for the batch would be the clone `CLAUDE.md` prohibits.
+		does: "run one child of a batch end to end in an isolated unit — an epic's child or one named issue of a `backlogrun` alike — plan, verification gate, PR, merge — and return only its summary to the parent loop",
+		verifier:
+			"the parent reads the child's state from GitHub with `pnpm josh issue:state`, not from the summary; a child reported done but not merged is still open, which is the failure showing rather than a run continuing, and its own gate, `/code-review` and CI ran inside the unit before `followup` would touch the PR",
+	},
+	{
+		name: 'followup-filing',
+		// The late-run follow-up filing chain — issue:scout → file the Issue → epic:bundle → epic --add
+		// — is a dependency chain `batch:guard` correctly keeps one call per step, and what makes it
+		// expensive is the ~340k context it runs in at the tail of a run, not the step count
+		// (joshuafolkken/kit#1892). A fresh unit runs the same chain at a small context, and the review
+		// round cap already composed the finding text, so what the unit is handed is mechanical: run the
+		// four commands and act on their deterministic answers. This is not `batch:guard`'s business —
+		// the chain stays one call per step; delegation only moves it to a cheaper context.
+		does: 'run the late-run follow-up filing chain in an isolated unit — issue:scout, file the Issue, epic:bundle, epic --add — given the finding text the parent already composed, and return the new Issue number and the epic:bundle answer',
+		verifier:
+			"the parent reads the filed Issue from GitHub with `pnpm josh issue:state <new>`, not the unit's summary; a follow-up reported filed but not created is still absent, the way `epic-child`'s reported-done-but-not-merged child is still open. The finding text came from the parent and `issue:scout` / `epic:bundle` are deterministic, so the unit's work is the mechanical execution `issue:state` confirms",
+	},
+	{
+		name: 'implementation-unit',
+		// The Step 0 change list already decided *what* to change — that design stays in the main line,
+		// which is why `design` is rejected below. What is delegated is the *writing* of one unit of that
+		// list, and only a unit whose files are disjoint from every other dispatched unit: two subagents
+		// editing one file in parallel race on it. `pnpm josh fanout` confirms that disjointness
+		// mechanically, so the split is read off the file sets rather than judged (joshuafolkken/kit#2345).
+		does: 'implement one file-disjoint unit of the Step 0 change list in an isolated subagent — the files it edits shared with no other dispatched unit, confirmed by `pnpm josh fanout` — and return the edited files, never a summary standing in for the diff; the main line keeps integration and the verification gate. Units that share a file, or an Issue that will not split, stay serial',
+		verifier:
+			"the parent runs the whole integrated change through `pnpm josh gate` and a `/code-review` subagent it would run anyway — a unit's mistake fails the same gate and review a serial edit passes through, so delegating writes nothing the backstop does not already catch, and the `pnpm josh fanout` disjointness removes the one failure parallelism adds, two units colliding on a file",
+	},
+	{
+		name: 'survey',
+		does: 'read across many files and report where something appears — every reference to a symbol, which documents carry a marker',
+		verifier:
+			'the reported locations are checked directly; a fabricated or missed location does not survive one `grep` of what it claimed',
+	},
+	{
+		name: 'investigation',
+		// Not `survey`: that row reports *where* something appears and is checked by one `grep`, while
+		// this one reports *how the subject works* and is checked by opening the lines it cited. The two
+		// verifiers differ, so widening `survey` would put both in one field and lose the boundary below.
+		// **No ordinal.** `${N}rd` would print `1rd` for any other threshold, past a test that only looks
+		// for the numeral, so the count is phrased as a plain "N or more".
+		does: `read the Issue's subject to find out how it currently works — once ${String(INVESTIGATION_FILE_THRESHOLD)} or more files the run will not edit have to be read — and return the conclusion plus the \`file:line\` citations that support it, never the file text, which would put the cost back where it was. A throwaway probe script is written, run and deleted inside the unit, which returns its output alone`,
+		verifier:
+			'the parent opens the cited lines; a conclusion those lines do not support fails there, and reading a handful of cited regions costs far less than redoing the reading. The unit reports what the code does and never what to change — deciding that is `diagnosis`, which stays kept, so a unit returning a root cause would be delegating the rejected row under this name',
+	},
+]
+
+// Steps that were considered and are **not** delegatable, kept as a list rather than dropped: the
+// next person to propose one of them should find the reason rather than re-derive it.
+interface RejectedStep {
+	name: string
+	because: string
+}
+
+const REJECTED_STEPS: ReadonlyArray<RejectedStep> = [
+	{
+		name: 'notify-body',
+		because:
+			'no verifier. A notification with a wrong body is sent and read as though it were right; nothing in the run disagrees with it afterwards',
+	},
+	{
+		name: 'issue-comment',
+		because:
+			'no verifier. A decision log or completion comment that says the wrong thing is the record, so there is nothing left to check it against',
+	},
+	{
+		name: 'status-read',
+		because:
+			'a misread routes the run to the wrong child, and no later step disagrees. Running the status command is already cheap; what is expensive is acting on it, which is not this step',
+	},
+	{
+		name: 'diagnosis',
+		because: 'a wrong root cause produces a fix that passes the gate and leaves the defect',
+	},
+	{
+		name: 'design',
+		because: 'the cost of a wrong design is paid by every step after it',
+	},
+	{
+		name: 'split-assessment',
+		because: 'a missed split widens one Issue into a batch nobody authorized',
+	},
+	{
+		name: 'review',
+		because: 'the review is the last thing between a defect and a merge; a cheaper one finds less',
+	},
+]
+
+function find_step(name: string): DelegatableStep | undefined {
+	return DELEGATABLE_STEPS.find((step) => step.name === name.trim())
+}
+
+function verdict_for(name: string): DelegationVerdict {
+	return find_step(name) === undefined ? KEEP_VERDICT : DELEGATE_VERDICT
+}
+
+function rejection_for(name: string): RejectedStep | undefined {
+	return REJECTED_STEPS.find((step) => step.name === name.trim())
+}
+
+// Why the answer is what it is. A verdict with no reason is a rule an agent cannot check itself
+// against, and `keep` is the answer that most needs one — most of the time it means "nobody has
+// listed this", not "this was judged too risky".
+function reason_for(name: string): string {
+	const step = find_step(name)
+
+	if (step !== undefined) return `delegatable: ${step.verifier}`
+
+	const rejected = rejection_for(name)
+
+	if (rejected !== undefined) return `kept deliberately: ${rejected.because}`
+
+	return 'kept by default: not on the delegatable list, and the list is the whole of it'
+}
+
+const delegation_policy = {
+	DELEGATE_VERDICT,
+	INVESTIGATION_FILE_THRESHOLD,
+	KEEP_VERDICT,
+	DELEGATABLE_STEPS,
+	REJECTED_STEPS,
+	find_step,
+	verdict_for,
+	rejection_for,
+	reason_for,
+}
+
+export type { DelegatableStep, DelegationVerdict, RejectedStep }
+export { delegation_policy }

package/scripts/delegation/duplicate-read-guard.ts

@@ -0,0 +1,244 @@
+#!/usr/bin/env tsx
+import { statSync } from 'node:fs'
+import { text } from 'node:stream/consumers'
+import { fileURLToPath } from 'node:url'
+import { hook_decision } from '#scripts/josh/hook-decision'
+import { lane_guard_policy, type LaneGuardMode } from '#scripts/lane/lane-guard-policy'
+import { json_value } from '#scripts/lib/json-value'
+import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
+import { time_spans, type Span } from '#scripts/time-runtime/time-spans'
+import { investigation_reads } from './investigation-reads'
+
+// Refuse the second whole-file `Read` of a path whose content has not changed since the run last read
+// it (joshuafolkken/kit#2298). Measured across the latest five lanes, a run re-read the same unchanged
+// path 8.0 times on average — `#2282` read `pre-gate-cut.md` three times — and each round trip pays
+// ~17 seconds to return text the run already holds. The remedy is the one `investigation-guard.ts`
+// already proved: intervene in the `PreToolUse` decision rather than describe the rule in prose.
+//
+// **It is unchanged content that is caught, never a repeat read.** The transcript says *when* the run
+// last read the path; the filesystem says *whether* it has changed since. A file whose `mtime` is
+// newer than that read has been edited — or merged, or grown by a background task — so the re-read is
+// let through; only a file untouched since the read returns nothing new. Reading the change off the
+// disk rather than off the transcript is what makes an edit, a `git` checkout and a `tasks/*.output`
+// that grew all read the same: any of them moves the `mtime`.
+//
+// **How it speaks is decided by the one-place lane enumeration, exactly as the batching guard's is.**
+// On the interactive main line a refusal is guidance, so the guard `refuse`s; in a dispatched lane
+// child a denial ends the headless turn with nothing committed (joshuafolkken/kit#2138), and the
+// duplicates the Issue measured are in those very children — so there it is a `notice`, nudging the run
+// without killing it. `lane-guard-policy.ts` is the single source of both modes.
+//
+// **The escape hatch is on by default**, for `investigation-guard.ts`'s reason: a distributed guard
+// nobody enables leaves the Issue where it started. The variable buys a way to switch it off without
+// editing the settings file — debugging the guard, or a session whose re-reads really are all needed.
+const SWITCH_ENV_KEY = 'JOSH_DUPLICATE_READ_GUARD'
+const LANE_GUARD_ID = 'duplicate-read'
+const STAMP_PREFIX = 'josh-duplicate-read-guard-'
+const NOTICE_STAMP_PREFIX = 'josh-duplicate-read-notice-'
+const READ_TOOL = 'Read'
+// A glob resolves to a literal path with a `*` in it, which names no single file to stat.
+const GLOB_CHARACTERS = /[*?]/u
+
+// What the refusal tells the model — the deny reason is the only text that reaches it, so it has to
+// name why the read was stopped and how to proceed. A run refused and told nothing reads it as a
+// broken tool.
+const REASON = `⛔ duplicate read: this file was already read in this session and has not changed since (its mtime predates that read), so reading it again returns nothing new. Scroll up to the earlier result instead of re-reading it. A read with a new offset/limit, or of a file that has since changed, is allowed; set \`JOSH_DUPLICATE_READ_GUARD=off\` to disable this guard.`
+
+// The same guidance carried without a `permissionDecision`, for a dispatched lane child where a denial
+// would end the turn (joshuafolkken/kit#2138). It nudges rather than blocks, so the run survives.
+const NOTICE = `⚠ duplicate read: this file was already read in this session and has not changed since, so re-reading it returns nothing new — scroll up to the earlier result instead of re-reading it. Set \`JOSH_DUPLICATE_READ_GUARD=off\` to silence this.`
+
+// **A paginated read is a read of a different region, not a repeat.** A run that read lines 1–100 and
+// now wants 101–200 needs the second call, so a read carrying an `offset` or a `limit` is never the
+// whole-file re-read this guard is about — the count the Issue measured is whole-file reads.
+function is_paginated(input: Record<string, unknown>): boolean {
+	return input['offset'] !== undefined || input['limit'] !== undefined
+}
+
+// A `file_path` that names one readable file: a non-empty string that is not a glob. A glob resolves
+// to a literal path with a `*` in it, which names no single file to stat.
+function names_one_file(file_path: unknown): file_path is string {
+	return typeof file_path === 'string' && file_path !== '' && !GLOB_CHARACTERS.test(file_path)
+}
+
+// The absolute path of a refusable whole-file `Read`, or `undefined` for any call this guard leaves
+// alone: a non-`Read` tool, a paginated read, or a target that names no single file. Resolved through
+// `investigation-reads.ts` so the two ways a path reaches here — a tool field and a transcript span —
+// compare as one string.
+function read_target(call: GuardedCall): string | undefined {
+	if (call.name !== READ_TOOL || !json_value.is_record(call.input)) return undefined
+
+	const { input } = call
+
+	if (is_paginated(input) || !names_one_file(input['file_path'])) return undefined
+
+	return investigation_reads.resolved(input['file_path'])
+}
+
+function is_refusable_call(call: GuardedCall): boolean {
+	return read_target(call) !== undefined
+}
+
+// A read the run made and that returned — a denied or errored read carried no text into the prompt, so
+// it is not a read this guard measures against. It is `investigation-reads.ts`'s own exclusion, asked
+// here of a `Read` span alone.
+function is_successful_read(span: Span): boolean {
+	const is_read = investigation_reads.READ_TOOLS.has(span.label)
+
+	return is_read && span.outcome !== time_spans.FAILED_OUTCOME
+}
+
+function reads_target(span: Span, target: string): boolean {
+	return span.targets.some((one) => investigation_reads.resolved(one) === target)
+}
+
+// **The instant the run last read this exact path, or `NEVER_MS` where the tail holds no such read.**
+// The most recent successful read wins: an earlier read that has since been superseded says nothing
+// about whether the content is current. The tail is the same bounded window the other guards read, so
+// a first read that has scrolled out reads as "never read" — a miss, never a false refusal.
+function last_read_ms(spans: ReadonlyArray<Span>, target: string): number {
+	const times = spans
+		.filter((span) => is_successful_read(span) && reads_target(span, target))
+		.map((span) => span.ended_ms)
+
+	return times.length === 0 ? hook_decision.NEVER_MS : Math.max(...times)
+}
+
+// The file's modification time in epoch milliseconds, comparable to a span's `ended_ms` because both
+// are this machine's wall clock. **A stat that fails allows the call** — a deleted or unreadable file
+// is not something to refuse over, and "could not read mtime/size" is the fallback the Issue names.
+function file_mtime_ms(target: string): number | undefined {
+	try {
+		return statSync(target).mtimeMs
+	} catch {
+		return undefined
+	}
+}
+
+// What the rule needs about the run: when the target was last read, and when the window opens.
+interface ReadWindow {
+	last_ms: number
+	window_start_ms: number
+}
+
+function read_window(tail: string, target: string): ReadWindow {
+	const { spans, started_ms } = time_spans.parse_timeline(tail)
+
+	return { last_ms: last_read_ms(spans, target), window_start_ms: started_ms }
+}
+
+// **The re-read returns nothing new.** The path was read before (`last_ms` is set) and the file has
+// not changed since (`mtime` predates that read). A missing stat is not "unchanged" — it is the
+// fallback that allows the call.
+function is_unchanged_reread(last_ms: number, mtime: number | undefined): boolean {
+	if (mtime === undefined || last_ms === hook_decision.NEVER_MS) return false
+
+	return mtime < last_ms
+}
+
+// **One firing per accumulation, re-armed by a later read and by nothing else.** A run spoken to once
+// and reading on anyway is not spoken to again — a false positive costs one round trip, never the wedge
+// of the same call flagged on every look. It re-arms when a fresh successful read of the target lands
+// after the last firing (a new redundant episode), or when that firing has scrolled out of the window,
+// which is `investigation-reads.ts`'s own pair of arms. `fired_at_ms` is the refusal's stamp on the
+// main line and the notice's own stamp in a lane child, so the two dedupe independently.
+function is_rearmed(window: ReadWindow, fired_at_ms: number): boolean {
+	if (fired_at_ms === hook_decision.NEVER_MS || fired_at_ms < window.window_start_ms) return true
+
+	return window.last_ms > fired_at_ms
+}
+
+// The pure rule, shared by the refusal and the notice: is this call an unchanged re-read that the
+// enumeration's mode should act on, given whatever this disposition last fired at.
+function is_redundant_reread(tail: string, call: GuardedCall, fired_at_ms: number): boolean {
+	const target = read_target(call)
+
+	if (target === undefined) return false
+
+	const window = read_window(tail, target)
+
+	if (!is_unchanged_reread(window.last_ms, file_mtime_ms(target))) return false
+
+	return is_rearmed(window, fired_at_ms)
+}
+
+// **How this guard behaves for the session in hand, from the one-place enumeration** — `refuse` on the
+// main line, `notice` in a dispatched lane child (joshuafolkken/kit#2298). The enumeration reads the
+// dispatch mark against this checkout's own issue only for a mode it would change, so a person working
+// in a lane sees the guard refuse exactly as the main line does.
+function duplicate_mode(): LaneGuardMode {
+	return lane_guard_policy.mode_here(LANE_GUARD_ID)
+}
+
+// A candidate call is reached unless the enumeration turns the guard fully `off`; today no mode does,
+// but the three-valued wrapper keeps that a change to the enumeration rather than to this file.
+function is_candidate(call: GuardedCall): boolean {
+	return is_refusable_call(call) && duplicate_mode() !== 'off'
+}
+
+// A refusable call is refused only where the mode is `refuse`. A lane child is `notice`, so it reaches
+// here and is withheld the refusal — the notice branch carries the guidance instead, because a refusal
+// ends a headless child's turn (joshuafolkken/kit#2138).
+function should_block_here(tail: string, call: GuardedCall, refused_at_ms: number): boolean {
+	if (duplicate_mode() !== 'refuse') return false
+
+	return is_redundant_reread(tail, call, refused_at_ms)
+}
+
+// The `notice`-mode branch, reached in a dispatched lane child. It reads the notice's own last-fired
+// instant, so a notice never spends the refusal's stamp and re-arms on the same "a newer read landed"
+// rule the refusal does.
+function should_notify_here(tail: string, call: GuardedCall, notified_at_ms: number): boolean {
+	if (duplicate_mode() !== 'notice') return false
+
+	return is_redundant_reread(tail, call, notified_at_ms)
+}
+
+const GUARD = hook_decision.create_transcript_guard({
+	prefix: STAMP_PREFIX,
+	switch_key: SWITCH_ENV_KEY,
+	is_candidate,
+	should_block: should_block_here,
+	reason: REASON,
+	notify: {
+		prefix: NOTICE_STAMP_PREFIX,
+		should_notify: should_notify_here,
+		text: () => NOTICE,
+	},
+})
+
+const duplicate_read_refusal = GUARD.refusal
+const duplicate_read_outcome = GUARD.outcome
+const { is_enabled, refusal_path } = GUARD
+const notice_refusal_path = hook_decision.create_refusal_stamp(NOTICE_STAMP_PREFIX).path
+const { deny_envelope, DISABLED_VALUES } = hook_decision
+
+const duplicate_reads = {
+	REASON,
+	NOTICE,
+	SWITCH_ENV_KEY,
+	is_candidate,
+	is_rearmed,
+	is_redundant_reread,
+	is_refusable_call,
+	is_unchanged_reread,
+	last_read_ms,
+	read_target,
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	if (process.stdin.isTTY) hook_decision.report_no_payload('duplicate-read:guard')
+	else hook_decision.write_outcome(await text(process.stdin), duplicate_read_outcome)
+}
+
+export {
+	deny_envelope,
+	DISABLED_VALUES,
+	duplicate_read_outcome,
+	duplicate_read_refusal,
+	duplicate_reads,
+	is_enabled,
+	notice_refusal_path,
+	refusal_path,
+	SWITCH_ENV_KEY,
+}

package/scripts/delegation/fanout-cli.ts

@@ -0,0 +1,61 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { fanout, type FanoutUnit } from './fanout'
+
+// `josh fanout <unit-files> <unit-files> …` — may the Step 0 change list be cut into file-disjoint
+// units and dispatched in one fan-out turn? (joshuafolkken/kit#2345)
+//
+// A command rather than a paragraph, for the reason `josh delegate` is one: "these units look
+// independent" is a judgement made under the same cost pressure, and the answer is mechanical — read
+// off the file sets. Each argument is one unit's comma-separated file list; the verdict is on stdout
+// so `$(josh fanout …)` reads it, the reason on stderr so a person sees why.
+
+const ARGV_OFFSET = 2
+const FAILURE_EXIT_CODE = 1
+const USAGE =
+	'Usage: josh fanout <unit-files> <unit-files> [<unit-files> …]  (each a comma-separated file list)'
+
+const FILE_SEPARATOR = ','
+
+// One argument to one unit: split on commas, trim, drop the empties a stray comma leaves.
+function parse_unit(argument: string): FanoutUnit {
+	const files = argument
+		.split(FILE_SEPARATOR)
+		.map((file) => file.trim())
+		.filter((file) => file !== '')
+
+	return { files }
+}
+
+// Refused when nothing was passed, or when a unit parses to no files at all — an empty unit says
+// nothing about disjointness and is a typo, not a verdict.
+function is_refused(units: ReadonlyArray<FanoutUnit>): boolean {
+	return units.length === 0 || units.some((unit) => unit.files.length === 0)
+}
+
+function run(argv: ReadonlyArray<string>): number {
+	const units = argv.map((argument) => parse_unit(argument))
+
+	if (is_refused(units)) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const result = fanout.fanout_result(units)
+
+	console.info(result.verdict)
+	console.error(result.reason)
+
+	return 0
+}
+
+function main(argv: ReadonlyArray<string>): void {
+	process.exitCode = run(argv)
+}
+
+const fanout_cli = { USAGE, parse_unit, is_refused, run, main }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) main(process.argv.slice(ARGV_OFFSET))
+
+export { fanout_cli }

package/scripts/delegation/fanout.ts

@@ -0,0 +1,95 @@
+// Whether the Step 0 change list can be cut into file-disjoint units and dispatched in one fan-out
+// turn, or must stay serial because two proposed units would edit the same file (joshuafolkken/kit#2345).
+//
+// **File-disjointness is the necessary condition, and it is mechanical.** Two subagents editing the
+// same file in parallel race on that file — the later write lands on top of the earlier, or the gate
+// has to reconcile a collision the parallelism was supposed to save. So the split is refused the
+// moment any file appears in more than one unit, and the default is serial: fewer than two units is
+// nothing to run in parallel. Nothing here is a judgement — the answer is read off the file sets.
+
+type FanoutVerdict = 'parallel' | 'serial'
+
+const PARALLEL_VERDICT: FanoutVerdict = 'parallel'
+const SERIAL_VERDICT: FanoutVerdict = 'serial'
+
+// One unit is nothing to parallelize; the fan-out only pays off from two independent units up.
+const MIN_UNITS_TO_PARALLELIZE = 2
+
+// A file carried by this many units or more is shared, so the units cannot run in parallel.
+const SHARED_THRESHOLD = 2
+
+interface FanoutUnit {
+	// The files this one unit edits, already split from the argument and trimmed.
+	files: ReadonlyArray<string>
+}
+
+interface FanoutResult {
+	verdict: FanoutVerdict
+	// The reason, for a person; the verdict alone is what a shell reads.
+	reason: string
+	// The files that appear in more than one unit — empty on a `parallel` verdict.
+	overlaps: ReadonlyArray<string>
+}
+
+// The distinct files one unit edits. De-duplicated, so a file listed twice inside one unit is not
+// counted as an overlap with anyone else.
+function unit_files(unit: FanoutUnit): Array<string> {
+	return [...new Set(unit.files)]
+}
+
+// How many units carry each file, across all units.
+function file_counts(units: ReadonlyArray<FanoutUnit>): Map<string, number> {
+	const counts = new Map<string, number>()
+	const files = units.flatMap((unit) => unit_files(unit))
+
+	for (const file of files) {
+		counts.set(file, (counts.get(file) ?? 0) + 1)
+	}
+
+	return counts
+}
+
+// The files carried by two or more units, sorted.
+function overlapping_files(units: ReadonlyArray<FanoutUnit>): Array<string> {
+	return [...file_counts(units)]
+		.filter(([, count]) => count >= SHARED_THRESHOLD)
+		.map(([file]) => file)
+		.toSorted((left, right) => left.localeCompare(right))
+}
+
+// The verdict for a set of proposed units. Serial below two units, serial on any shared file naming
+// what collides, parallel only when every unit's file set is disjoint from every other's.
+function fanout_result(units: ReadonlyArray<FanoutUnit>): FanoutResult {
+	if (units.length < MIN_UNITS_TO_PARALLELIZE) {
+		return {
+			verdict: SERIAL_VERDICT,
+			reason: 'fewer than two units — nothing to run in parallel',
+			overlaps: [],
+		}
+	}
+
+	const overlaps = overlapping_files(units)
+
+	if (overlaps.length > 0) {
+		const reason = `units share ${overlaps.join(', ')} — parallel edits would race, so run serial`
+
+		return { verdict: SERIAL_VERDICT, reason, overlaps }
+	}
+
+	return {
+		verdict: PARALLEL_VERDICT,
+		reason: `${String(units.length)} file-disjoint units`,
+		overlaps: [],
+	}
+}
+
+const fanout = {
+	PARALLEL_VERDICT,
+	SERIAL_VERDICT,
+	MIN_UNITS_TO_PARALLELIZE,
+	overlapping_files,
+	fanout_result,
+}
+
+export type { FanoutResult, FanoutUnit, FanoutVerdict }
+export { fanout }