@joshuafolkken/kit 1.1010.0 → 1.1050.0

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

@@ -1,5 +1,4 @@
 #!/usr/bin/env tsx
-import { readFile } from 'node:fs/promises'
 import { fileURLToPath } from 'node:url'
 import { observation_ledger_home } from '#scripts/observations/observation-ledger-home'
 import { review_finding_ledger, type CategoryCount } from './review-finding-ledger'
@@ -29,16 +28,10 @@ function format_report(counts: ReadonlyArray<CategoryCount>, zero_rounds: number
 	return `findings by category:\n${body}\n${zero_line(zero_rounds)}`
 }
 
-async function read_ledger(ledger_path: string): Promise<string> {
-	try {
-		return await readFile(ledger_path, 'utf8')
-	} catch {
-		return ''
-	}
-}
-
-async function run(ledger_path: string = observation_ledger_home.ledger_path()): Promise<number> {
-	const content = await read_ledger(ledger_path)
+// Every issue's file of the ledger directory is counted (joshuafolkken/kit#2919): a recurring category
+// is one whichever issue recorded each sighting.
+async function run(root: string = observation_ledger_home.ledger_root()): Promise<number> {
+	const content = (await observation_ledger_home.read(root)) ?? ''
 	const counts = review_finding_ledger.category_counts(content)
 
 	console.info(format_report(counts, review_finding_ledger.zero_round_count(content)))

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

@@ -7,8 +7,8 @@ import { review_record, type RecordVerdict } from './review-record'
 
 // `josh review:record --issue <N> [<category>:<severity>:<file> ...]` — the one write path for a
 // `/code-review` round's findings (joshuafolkken/kit#2325). It appends a `- rf:` line per finding to
-// the observation ledger, which `pnpm josh observations:flush` then commits like any other ledger
-// change. **A call with no findings is a zero-finding round, and it still writes one line** — so the
+// the issue's own file of the observation ledger, which the run's commit carries like any other
+// ledger change. **A call with no findings is a zero-finding round, and it still writes one line** — so the
 // round that found nothing is recorded rather than mistaken for a round nobody reviewed.
 //
 // `josh review:record --check --issue <N>` is the read half `pnpm josh followup` runs before it
@@ -121,14 +121,14 @@ function check_line(verdict: RecordVerdict): string {
 	return verdict.status === 'ok' ? RECORDED_LINE : NOT_REQUIRED_LINE
 }
 
-async function run_check(issue: string | undefined, ledger_path: string): Promise<number> {
+async function run_check(issue: string | undefined, root: string): Promise<number> {
 	if (issue === undefined || !ISSUE_PATTERN.test(issue)) {
 		console.error(CHECK_USAGE)
 
 		return FAILURE_EXIT_CODE
 	}
 
-	const verdict = await review_record.check(Number(issue), ledger_path)
+	const verdict = await review_record.check(Number(issue), root)
 
 	if (verdict.status === 'ok' || verdict.status === 'not-required') {
 		console.info(check_line(verdict))
@@ -141,7 +141,9 @@ async function run_check(issue: string | undefined, ledger_path: string): Promis
 	return FAILURE_EXIT_CODE
 }
 
-async function run_record(parsed: Parsed, now: Date, ledger_path: string): Promise<number> {
+// The round lands in its own issue's file (joshuafolkken/kit#2919), so two lanes recording at once
+// write two files, and their pull requests never conflict on the ledger.
+async function run_record(parsed: Parsed, now: Date, root: string): Promise<number> {
 	const request = to_request(parsed)
 
 	if (request === undefined) {
@@ -151,6 +153,7 @@ async function run_record(parsed: Parsed, now: Date, ledger_path: string): Promi
 	}
 
 	const lines = build_lines(request, today(now))
+	const ledger_path = observation_ledger_home.issue_path(request.issue, root)
 
 	await observation_ledger_home.append(ledger_path, lines)
 	console.info(confirmation(lines.length, ledger_path))
@@ -158,13 +161,13 @@ async function run_record(parsed: Parsed, now: Date, ledger_path: string): Promi
 	return 0
 }
 
-// **The default is the primary checkout's ledger, even inside a lane** (joshuafolkken/kit#2419). A line
-// appended to a lane's own copy never reached the default branch — the lane's flush is refused and
-// `lane:close` does not carry the file — while `--check` read that same copy and let the merge through.
+// **The default is the work tree the command runs in, a lane's inside a lane** (joshuafolkken/kit#2919).
+// The line rides that tree's own commit or `pnpm josh followup`'s pre-merge ledger commit, and
+// `--check` reads the same tree, so the two halves can never disagree about where the round is.
 async function run(
 	argv: ReadonlyArray<string>,
 	now: Date,
-	ledger_path: string = observation_ledger_home.ledger_path(),
+	root: string = observation_ledger_home.ledger_root(),
 ): Promise<number> {
 	const parsed = parse_argv(argv)
 
@@ -174,9 +177,9 @@ async function run(
 		return FAILURE_EXIT_CODE
 	}
 
-	if (parsed.check) return await run_check(parsed.issue, ledger_path)
+	if (parsed.check) return await run_check(parsed.issue, root)
 
-	return await run_record(parsed, now, ledger_path)
+	return await run_record(parsed, now, root)
 }
 
 async function main(argv: ReadonlyArray<string>): Promise<void> {

package/scripts/review/review-record.ts

@@ -1,4 +1,3 @@
-import { readFile } from 'node:fs/promises'
 import { observation_ledger_home } from '#scripts/observations/observation-ledger-home'
 import { review_finding_ledger } from './review-finding-ledger'
 
@@ -29,24 +28,15 @@ interface RecordVerdict {
 	issue?: number
 }
 
-// `undefined` for both "the file is absent" and "the file could not be read" — they are the same
-// answer here, a ledger this checkout does not keep, and the caller turns that into `not-required`.
-async function read_ledger(ledger_path: string): Promise<string | undefined> {
-	try {
-		return await readFile(ledger_path, 'utf8')
-	} catch {
-		return undefined
-	}
-}
-
-// The default is the primary checkout's ledger, the one `review:record` writes from a lane
-// (joshuafolkken/kit#2419) — a cwd-relative default read the lane's copy, so the followup gate refused
-// every round recorded from a lane (joshuafolkken/kit#2431).
+// The default is the work tree the check runs in — the one `review:record` wrote to, a lane's in a
+// lane (joshuafolkken/kit#2919). Every file of the directory is read, so the round is found whichever
+// file holds it; a directory that is not there answers `undefined`, a ledger this checkout does not
+// keep, which becomes `not-required`.
 async function check(
 	issue: number,
-	ledger_path: string = observation_ledger_home.ledger_path(),
+	root: string = observation_ledger_home.ledger_root(),
 ): Promise<RecordVerdict> {
-	const content = await read_ledger(ledger_path)
+	const content = await observation_ledger_home.read(root)
 
 	if (content === undefined) return { status: 'not-required' }
 	if (review_finding_ledger.has_issue_record(content, issue)) return { status: 'ok', issue }

package/scripts/review/review-stamps.ts

@@ -59,10 +59,15 @@ const TEST_RELATED_PREFIX = 'josh-test-related-stamp-'
 const GATE_PREFIX = 'josh-gate-stamp-'
 const IN_FLIGHT_PREFIX = 'josh-gate-running-'
 const ROUND_ONE_PREFIX = 'josh-review-round1-'
+const BRIEFED_PREFIX = 'josh-review-briefed-'
 
 const gate_stamp: FileMapStampAccess = file_map_stamp.create(GATE_PREFIX, PROJECT_ROOT)
 const in_flight_stamp: FileMapStampAccess = file_map_stamp.create(IN_FLIGHT_PREFIX, PROJECT_ROOT)
 const round_one_stamp: FileMapStampAccess = file_map_stamp.create(ROUND_ONE_PREFIX, PROJECT_ROOT)
+// **The tree the latest round-1 brief handed out, retaken on every brief** (joshuafolkken/kit#2945).
+// The round-1 snapshot is kept from the first brief of a run, so it is not the tree a later review
+// read — a resume narrowed against it would skip a file put back to that older content.
+const briefed_stamp: FileMapStampAccess = file_map_stamp.create(BRIEFED_PREFIX, PROJECT_ROOT)
 const lint_related_stamp: FileMapStampAccess = file_map_stamp.create(
 	LINT_RELATED_PREFIX,
 	PROJECT_ROOT,
@@ -97,6 +102,8 @@ function clear_round_one(target?: string): void {
 }
 
 const review_stamps = {
+	BRIEFED_PREFIX,
+	briefed_stamp,
 	clear_round_one,
 	GATE_PREFIX,
 	gate_stamp,

package/scripts/rules/decision-oracle.ts

@@ -47,7 +47,7 @@ const HUMAN_REVIEW = 'human-review'
 // test. `LIVE` is the silent norm; `STOPPED` and `UNKNOWN` lead the difference lines.
 const LIVE = 'live'
 const STOPPED = 'stopped'
-// The verdicts `epic --reconcile` prints; kept in step with the `git_epic_reconcile` constants in its
+// The verdicts `epic --reconcile` prints; kept in step with the `epic_reconcile` constants in its
 // test.
 const RECONCILED = 'reconciled'
 const NOTHING_TO_RECONCILE = 'nothing to reconcile'
@@ -302,7 +302,7 @@ const DECISION_ORACLES: ReadonlyArray<DecisionOracle> = [
 		decision: 'Whether cross-file or cross-repository code duplication exists',
 		args: '',
 		vocabulary: ['clean', 'clones:'],
-		single_source: 'prompts/collaboration-workflow/no-clones.md',
+		single_source: 'prompts/collaboration-workflow/principles.md → クローン禁止',
 	},
 	{
 		name: 'epic:reconcile',

package/scripts/rules/implementation-cut.ts

@@ -50,7 +50,7 @@ function is_impl_cut_segment(segment: string): boolean {
 }
 
 // Whether this command takes the implementation-phase cut, segment-wise so a spelling quoted inside a
-// body is not read as the call, and alias-expanded so `pnpm josh rct --impl` is the same call.
+// body is not read as the call.
 function takes_the_impl_cut(command: string): boolean {
 	return shell_segments.segments_of(command).some((segment) => is_impl_cut_segment(segment))
 }

package/scripts/rules/issue-fold.ts

@@ -21,8 +21,7 @@ import { tail_commands } from './tail-commands'
 // "fold first". **No new predicate**: the filing trigger is `bash_triggers.is_issue_filing`, and the
 // prior-filing count is `filing_cap.prior_filing_count`, both reused verbatim.
 
-// `pnpm josh issue:fold`, the one act the rule asks for. The alias `isf` is expanded where the command
-// is read, so the canonical name matches both spellings.
+// `pnpm josh issue:fold`, the one act the rule asks for.
 const FOLD_NAMES: ReadonlySet<string> = new Set(['issue:fold'])
 
 // Keeping the rule: a call that runs the fold. Segment-wise, so a spelling quoted inside a filing's

package/scripts/rules/lane-carry-conflict.ts

@@ -29,8 +29,7 @@ import { shell_segments } from './shell-segments'
 
 // The parent backlogrun budget/ownership commands. A child never runs either: `run:carry` begins and
 // advances the run budget the parent owns, and `run:merge` counts a returned child into it. Named in
-// canonical form only — `shell_segments.is_josh_command` canonicalizes an alias (`rc`, `rmg`) before
-// the match, so `pnpm josh rmg` arrives as `run:merge`.
+// canonical form only — `shell_segments.is_josh_command` canonicalizes an alias before the match.
 const RUN_BUDGET_COMMANDS: ReadonlySet<string> = new Set(['run:merge', 'run:carry'])
 
 // A segment that invokes one of the parent's budget commands. Segment-wise and alias-expanded for the

package/scripts/rules/lane-park.ts

@@ -30,8 +30,7 @@ import { shell_segments } from './shell-segments'
 // the stop, the reason is a checklist rather than an accusation, and a child that already parked simply
 // reissues. One wasted round trip on the compliant path is the safe direction; a missed park is not.
 
-// `josh notify`, in either spelling — the alias `nf` is expanded to `notify` before this sees it, the
-// same way `pre-gate-cut.ts` matches `gate` through `ga`.
+// `josh notify`, named canonically — `shell_segments.is_josh_command` expands an alias before the match.
 const NOTIFY_COMMANDS: ReadonlySet<string> = new Set(['notify'])
 // The task type that marks a stop waiting on a person, taken quoted or bare so `--task-type
 // confirmation` and `--task-type=confirmation` read alike. A `progress` or `pr` notification is not a

package/scripts/rules/pre-gate-cut.ts

@@ -44,8 +44,8 @@ const HOLD_COMMANDS: ReadonlySet<string> = new Set(['run:hold'])
 // predicate exists to keep it out of.
 const HOLD_MODE_FLAG = /(?:^|\s)--release(?:[=\s]|$)/u
 
-// **Alias-expanded rather than matched as text**, so `pnpm josh ga` and `pnpm josh rct` are the same
-// calls as their canonical spellings. Segment-wise for the reason every other row here is: one shell
+// **Alias-expanded rather than matched as text**, so `pnpm josh ga` is the same call as `pnpm josh
+// gate`. Segment-wise for the reason every other row here is: one shell
 // line carries several commands, and a name quoted inside a body is not the command being invoked.
 //
 // **One reading of that question rather than one per name set.** Four predicates here differ only in

package/scripts/rules/rule-body-guard.ts

@@ -1,5 +1,5 @@
-import { existsSync, readFileSync } from 'node:fs'
 import { json_value } from '#scripts/lib/json-value'
+import { file_reader } from '#scripts/lib/read-file'
 import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
 import { bash_triggers } from './bash-triggers'
 import { shell_segments } from './shell-segments'
@@ -81,7 +81,7 @@ function string_field(input: Record<string, unknown>, key: string): string {
 // measure against. Injected so the suite controls it without touching the real filesystem, the way
 // `file-body.ts` injects its existence check. A new file reads as empty, so its whole body is added.
 function read_existing(file_path: string): string {
-	return existsSync(file_path) ? readFileSync(file_path, 'utf8') : ''
+	return file_reader.read_file_or_empty(file_path)
 }
 
 function texts_of(

package/scripts/rules/rule-value-cache.ts

@@ -0,0 +1,99 @@
+import { spawn } from 'node:child_process'
+import { mkdirSync, renameSync, statSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { file_reader } from '#scripts/lib/read-file'
+
+// The `rule:value` reading at the `backlogrun` loop head, without the loop waiting on it
+// (joshuafolkken/kit#2881). Measuring re-reads every transcript and takes minutes, and `backlog:offer`
+// ran it synchronously on every iteration, so each dispatch waited on it. The loop head now prints the
+// last reading from a cache and, when the last refresh is old enough, starts one in a detached process
+// — `josh rule:value --refresh` — so the next iteration prints the newer reading.
+//
+// **It reports and never fails**, as `rule:value` itself does: a missing cache, an unwritable directory
+// or a refresh that could not start prints at most nothing, and never changes the offer's answer.
+
+const CACHE_DIRECTORY = ['node_modules', '.cache', 'josh']
+const CACHE_FILE = 'rule-value.txt'
+// Touched when a refresh starts, so the loop head starts at most one per interval however often it runs.
+const STAMP_FILE = 'rule-value.stamp'
+const MS_PER_MINUTE = 60_000
+const REFRESH_MINUTES = 15
+const REFRESH_MS = REFRESH_MINUTES * MS_PER_MINUTE
+const REFRESH_ARGV = ['josh', 'rule:value', '--refresh']
+const PNPM = 'pnpm'
+const TEMPORARY_SUFFIX = '.tmp'
+
+interface CachePorts {
+	now: () => number
+	start_refresh: (cwd: string) => void
+}
+
+function cache_path(cwd: string, file: string): string {
+	return path.join(cwd, ...CACHE_DIRECTORY, file)
+}
+
+function read_cached(cwd: string): string | undefined {
+	return file_reader.read_if_readable(cache_path(cwd, CACHE_FILE))
+}
+
+function is_refresh_due(cwd: string, now_ms: number): boolean {
+	try {
+		return now_ms - statSync(cache_path(cwd, STAMP_FILE)).mtimeMs >= REFRESH_MS
+	} catch {
+		return true
+	}
+}
+
+function write_cache_file(cwd: string, file: string, text: string): void {
+	const target = cache_path(cwd, file)
+	const temporary = `${target}${TEMPORARY_SUFFIX}`
+
+	mkdirSync(path.dirname(target), { recursive: true })
+	writeFileSync(temporary, text)
+	renameSync(temporary, target)
+}
+
+function ignore_spawn_error(): void {
+	/* a refresh that could not start leaves the last reading in place */
+}
+
+// Detached with no descriptor shared, so the loop head exits — and a backgrounded caller completes —
+// without waiting on the measurement.
+function start_refresh_default(cwd: string): void {
+	const child = spawn(PNPM, REFRESH_ARGV, { cwd, detached: true, stdio: 'ignore' })
+
+	child.on('error', ignore_spawn_error)
+	child.unref()
+}
+
+const DEFAULT_PORTS: CachePorts = { now: Date.now, start_refresh: start_refresh_default }
+
+function refresh_if_due(cwd: string, ports: CachePorts): void {
+	if (!is_refresh_due(cwd, ports.now())) return
+
+	write_cache_file(cwd, STAMP_FILE, new Date(ports.now()).toISOString())
+	ports.start_refresh(cwd)
+}
+
+// The loop-head call: the last reading to stderr, then a refresh when one is due.
+function emit(cwd: string = process.cwd(), ports: CachePorts = DEFAULT_PORTS): void {
+	const cached = read_cached(cwd)
+
+	if (cached !== undefined) process.stderr.write(cached)
+
+	try {
+		refresh_if_due(cwd, ports)
+	} catch {
+		// A refresh that could not be recorded or started leaves the last reading in place.
+	}
+}
+
+// The detached refresh's body: the reading written whole, so a reader never sees half of one.
+function store(text: string, cwd: string = process.cwd()): void {
+	write_cache_file(cwd, CACHE_FILE, `${text}\n`)
+}
+
+const rule_value_cache = { CACHE_FILE, REFRESH_MS, STAMP_FILE, cache_path, emit, store }
+
+export type { CachePorts }
+export { rule_value_cache }

package/scripts/rules/rule-value-cli.ts

@@ -3,6 +3,7 @@ import { fileURLToPath } from 'node:url'
 import { cost_transcript, type SessionFile } from '#scripts/cost-runtime/cost-transcript'
 import { delivered_rules } from './delivered-rules'
 import { rule_value, type RuleReading } from './rule-value'
+import { rule_value_cache } from './rule-value-cache'
 
 // `josh rule:value` — what each delivered rule earns on the channel that carries it, one row per rule
 // (joshuafolkken/kit#2271). `rule_value.measure` was public but had no caller outside its own test, so
@@ -14,6 +15,8 @@ import { rule_value, type RuleReading } from './rule-value'
 // no measurable transcript prints `NO_TARGETS` and exits zero rather than erroring, so a fresh
 // checkout reads differently from a broken command.
 
+const ARGV_OFFSET = 2
+const REFRESH_FLAG = '--refresh'
 const PERCENT_SIGN = '%'
 const COLUMN_GAP = '  '
 const NO_TARGETS = 'no measurement targets'
@@ -98,24 +101,22 @@ function render(runs: ReadonlyArray<ReadonlyArray<string>>): string {
 		.join('\n')
 }
 
-// The loop-head call: `backlog:offer` writes this to stderr once per iteration, so a rule that never
-// fires appears as a printed row rather than as something a person has to go looking for.
-function emit(cwd: string = process.cwd()): void {
-	process.stderr.write(`${render(gather_runs(cwd))}\n`)
-}
+// `--refresh` is the detached measurement the `backlogrun` loop head starts: the reading goes to the
+// cache `backlog:offer` prints from, never to stdout (`rule-value-cache.ts`, joshuafolkken/kit#2881).
+function run_rule_value(argv: ReadonlyArray<string> = [], cwd: string = process.cwd()): number {
+	const reading = render(gather_runs(cwd))
 
-function run_rule_value(cwd: string = process.cwd()): number {
-	process.stdout.write(`${render(gather_runs(cwd))}\n`)
+	if (argv.includes(REFRESH_FLAG)) rule_value_cache.store(reading, cwd)
+	else process.stdout.write(`${reading}\n`)
 
 	return 0
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
-	process.exitCode = run_rule_value()
+	process.exitCode = run_rule_value(process.argv.slice(ARGV_OFFSET))
 }
 
 const rule_value_cli = {
-	emit,
 	gather_runs,
 	group_by_run,
 	render,

package/scripts/rules/rule-value.ts

@@ -9,7 +9,7 @@ import { delivered_rules, type MeasuredRule } from './delivered-rules'
 // (joshuafolkken/kit#1525).
 //
 // **It exists because the eviction order was decided by protection rather than by value.**
-// `.claude/skills/workflow-commands/rule-residency.md` recorded that when a rule is trimmed to keep a
+// `prompts/collaboration-workflow/residency.md` records that when a rule is trimmed to keep a
 // byte count, the sentence that goes is the one no marker pinned (joshuafolkken/kit#951) — so the
 // least-defended text leaves, never the least-useful. Nothing in the repository could tell the two
 // apart: `scripts/josh/hook-decision.ts` keeps a once-per-run stamp that answers "has this fired

package/scripts/run/run-carry-args.ts

@@ -1,4 +1,4 @@
-import { parseArgs } from 'node:util'
+import { cli_flags } from '#scripts/lib/cli-flags'
 import { run_carry, type CarryChange, type CarryClaimRequest, type CarryOwner } from './run-carry'
 import { run_issue_number } from './run-issue-number'
 
@@ -76,11 +76,7 @@ type Request =
 const READ_REQUEST: Request = { kind: 'read' }
 
 function read_arguments(argv: ReadonlyArray<string>): ParsedValues | undefined {
-	try {
-		return parseArgs({ args: [...argv], options: OPTIONS, strict: true }).values
-	} catch {
-		return undefined
-	}
+	return cli_flags.parse_or_undefined({ args: [...argv], options: OPTIONS, strict: true })?.values
 }
 
 function text_of(value: OptionValue): string | undefined {

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

@@ -10,7 +10,6 @@ import {
 	type RunCarry,
 } from './run-carry'
 import { run_carry_args, type CountRequest, type Request } from './run-carry-args'
-import { run_carry_flush } from './run-carry-flush'
 import { run_carry_stash } from './run-carry-stash'
 import { run_event_stream } from './run-event-stream'
 import { run_event_stream_emit } from './run-event-stream-emit'
@@ -344,16 +343,15 @@ async function count(
 // **A stop over a record that is still there pushes one ⏸️ confirmation before the record goes**
 // (joshuafolkken/kit#2136). `plan` is read from the record `--end` is about to remove, so the second
 // `--end` reads `none` and plans nothing — one stop never notifies twice. A clean `--end` passes no
-// reason and stays silent, because a completed run has its own notification. The batch's one ledger
-// flush rides the same read for the same reason (joshuafolkken/kit#2492, `run-carry-flush.ts`), and
-// runs last: it waits out a pull request's CI, so a flush cut short must find the record already gone
-// and the stop already announced. The closed-issue stash report (joshuafolkken/kit#2505,
-// `run-carry-stash.ts`) is once per invocation on the same read, and goes first because it is quick.
+// reason and stays silent, because a completed run has its own notification. The closed-issue stash
+// report (joshuafolkken/kit#2505, `run-carry-stash.ts`) is once per invocation on the same read.
+//
+// **No ledger flush rides it any more** (joshuafolkken/kit#2919): each lane merges its own ledger
+// lines with its own pull request, so there is nothing left in the primary checkout to flush.
 async function report_end(read: CarryRead): Promise<void> {
 	if (read.kind === 'none') return
 
 	await run_carry_stash.report_orphans()
-	await run_carry_flush.flush_ledger()
 }
 
 async function finish(

package/scripts/run/run-cut-args.ts

@@ -1,4 +1,4 @@
-import { parseArgs } from 'node:util'
+import { cli_flags } from '#scripts/lib/cli-flags'
 import { run_issue_number } from './run-issue-number'
 
 // `josh run:cut` turns its `argv` into one of four requests. The contract mirrors `run-carry-args.ts`:
@@ -47,18 +47,12 @@ type Request =
 	| { kind: 'end' }
 
 function read_arguments(argv: ReadonlyArray<string>): ParsedValues | undefined {
-	try {
-		const parsed = parseArgs({
-			args: [...argv],
-			options: OPTIONS,
-			strict: true,
-			allowPositionals: true,
-		})
-
-		return { values: parsed.values, positionals: parsed.positionals }
-	} catch {
-		return undefined
-	}
+	return cli_flags.parse_or_undefined({
+		args: [...argv],
+		options: OPTIONS,
+		strict: true,
+		allowPositionals: true,
+	})
 }
 
 // The issue is the sole positional, and it must be a real issue number: a cut relaunches

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

@@ -1,6 +1,7 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
-import { parseArgs } from 'node:util'
+import { cli_flags } from '#scripts/lib/cli-flags'
+import { error_text } from '#scripts/lib/error-message'
 import {
 	run_ending,
 	UNREADABLE_VERDICT,
@@ -56,11 +57,7 @@ interface ParsedArguments {
 }
 
 function read_arguments(argv: ReadonlyArray<string>): ParsedArguments | undefined {
-	try {
-		return parseArgs({ args: [...argv], options: OPTIONS, allowPositionals: true })
-	} catch {
-		return undefined
-	}
+	return cli_flags.parse_or_undefined({ args: [...argv], options: OPTIONS, allowPositionals: true })
 }
 
 function is_valid(parsed: ParsedArguments): boolean {
@@ -96,7 +93,7 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 	try {
 		return report(await run_ending.check(request))
 	} catch (error) {
-		return report_unreadable(error instanceof Error ? error.message : String(error))
+		return report_unreadable(error_text.message_of(error))
 	}
 }
 

package/scripts/run/run-event-stream.ts

@@ -1,4 +1,5 @@
 import { stamp_file } from '#scripts/josh/stamp-file'
+import { json_value } from '#scripts/lib/json-value'
 import { z } from 'zod'
 
 // The run's append-only, ordered event stream — the surface a reader who was away rebuilds the run's
@@ -143,11 +144,7 @@ function is_present(event: RunEvent | undefined): event is RunEvent {
 // A malformed line reads as no event rather than throwing, so one truncated append — a write that lost a
 // race — never makes the whole stream unreadable.
 function parse_line(line: string): RunEvent | undefined {
-	try {
-		return event_schema.safeParse(JSON.parse(line)).data
-	} catch {
-		return undefined
-	}
+	return event_schema.safeParse(json_value.parse_or_undefined(line)).data
 }
 
 // Every event on the stream, oldest first. An absent or unreadable file is an empty stream, the same

package/scripts/run/run-headless.ts

@@ -73,10 +73,27 @@ function is_owned_here(carry: RunCarry, ancestry: () => ReadonlySet<number>): bo
 	return carry.owner_pid !== undefined && ancestry().has(carry.owner_pid)
 }
 
-function is_driven_here(read: CarryRead | undefined, ancestry: () => ReadonlySet<number>): boolean {
-	if (read?.kind !== 'carried' || !is_driving(read)) return false
+function driven_here(
+	read: CarryRead | undefined,
+	ancestry: () => ReadonlySet<number>,
+): RunCarry | undefined {
+	if (read?.kind !== 'carried' || !is_driving(read)) return undefined
 
-	return is_owned_here(read.carry, ancestry)
+	return is_owned_here(read.carry, ancestry) ? read.carry : undefined
+}
+
+/**
+ * The live, un-handed-off carry record this session drives as the `backlogrun` parent, or `undefined`
+ * for a lane child or any session that does not own one. Returned rather than tested so a caller that
+ * also needs the record's counters (the parent cut's cap, joshuafolkken/kit#2947) reads it once.
+ */
+async function driving_carry(
+	source: EnvironmentSource = process.env,
+	ancestry: () => ReadonlySet<number> = lane_reap.own_ancestry,
+): Promise<RunCarry | undefined> {
+	if (lane_child_marker.marked_issue(source) !== undefined) return undefined
+
+	return driven_here(await read_carry_here(), ancestry)
 }
 
 /**
@@ -88,14 +105,13 @@ async function is_backlog_parent(
 	source: EnvironmentSource = process.env,
 	ancestry: () => ReadonlySet<number> = lane_reap.own_ancestry,
 ): Promise<boolean> {
-	if (lane_child_marker.marked_issue(source) !== undefined) return false
-
-	return is_driven_here(await read_carry_here(), ancestry)
+	return (await driving_carry(source, ancestry)) !== undefined
 }
 
 const run_headless = {
 	HEADLESS_ENV_KEY,
 	current_carry,
+	driving_carry,
 	environment,
 	is_backlog_parent,
 	is_headless,

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

@@ -1,6 +1,7 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
-import { parseArgs } from 'node:util'
+import { cli_flags } from '#scripts/lib/cli-flags'
+import { error_text } from '#scripts/lib/error-message'
 import { run_issue_number } from './run-issue-number'
 import {
 	MS_PER_MINUTE,
@@ -89,11 +90,7 @@ interface ParsedArguments {
 }
 
 function read_arguments(argv: ReadonlyArray<string>): ParsedArguments | undefined {
-	try {
-		return parseArgs({ args: [...argv], options: OPTIONS, allowPositionals: true })
-	} catch {
-		return undefined
-	}
+	return cli_flags.parse_or_undefined({ args: [...argv], options: OPTIONS, allowPositionals: true })
 }
 
 function is_valid_target(parsed: ParsedArguments): boolean {
@@ -154,7 +151,7 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 	try {
 		return report(await run_liveness.check(request))
 	} catch (error) {
-		return report_undetermined(error instanceof Error ? error.message : String(error))
+		return report_undetermined(error_text.message_of(error))
 	}
 }