@joshuafolkken/kit 1.1010.0 → 1.1035.0

package/scripts/git/main-sync.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { composite_arguments, USAGE_ERROR_EXIT_CODE } from '#scripts/josh/josh-composite-arguments'
+import { error_text } from '#scripts/lib/error-message'
 import { git_command } from './git-command'
 import { gone_branch, type PruneResult } from './gone-branch'
 
@@ -65,7 +66,7 @@ async function prune_quietly(default_branch: string): Promise<void> {
 	try {
 		report_prune(await gone_branch.prune(default_branch))
 	} catch (error) {
-		console.error(`branch prune skipped: ${error instanceof Error ? error.message : String(error)}`)
+		console.error(`branch prune skipped: ${error_text.message_of(error)}`)
 	}
 }
 
@@ -104,7 +105,7 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 	try {
 		return await dispatch(argv)
 	} catch (error) {
-		console.error(error instanceof Error ? error.message : String(error))
+		console.error(error_text.message_of(error))
 
 		return FAILURE_EXIT_CODE
 	}

package/scripts/git/schemas.ts

@@ -111,7 +111,7 @@ const rest_comment_schema = z.looseObject({
 // Labels come back as objects, so the name is picked out here rather than at every call site.
 const issue_label_schema = z.object({ name: z.string() })
 
-// `state` is optional because most readers ignore it — only `git-epic-add.ts` consults it, to refuse
+// `state` is optional because most readers ignore it — only `epic-add.ts` consults it, to refuse
 // adding a child to a closed epic (joshuafolkken/kit#2337). A reader that never asks the state field
 // still parses cleanly.
 const epic_subject_schema = z.object({

package/scripts/git/stash-pop-args.ts

@@ -1,4 +1,4 @@
-import { parseArgs } from 'node:util'
+import { cli_flags } from '#scripts/lib/cli-flags'
 
 // `josh stash:pop` turns its `argv` into a single request: the message of the stash to pop. Parsing
 // lives here, acting on the stack lives in `stash-pop-cli.ts`, and a malformed command line is
@@ -21,18 +21,12 @@ interface Request {
 }
 
 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 message is the sole positional and must be a non-empty string: an empty message matches every

package/scripts/git/stash-pop-cli.ts

@@ -1,4 +1,5 @@
 import { fileURLToPath } from 'node:url'
+import { error_text } from '#scripts/lib/error-message'
 import { git_stash } from './git-stash'
 import { stash_pop_args, type Request } from './stash-pop-args'
 
@@ -66,7 +67,7 @@ async function answer(request: Request): Promise<number> {
 }
 
 function report_unknown(error: unknown): number {
-	console.error(error instanceof Error ? error.message : String(error))
+	console.error(error_text.message_of(error))
 
 	return FAILURE_EXIT_CODE
 }

package/{scripts-ai → scripts/git}/telegram-test-logic.ts

@@ -1,5 +1,5 @@
-import type { TelegramSendInput, TelegramTaskType } from '../scripts/git/telegram-notify'
-import { cli_body } from '../scripts/josh/cli-body'
+import { cli_body } from '#scripts/josh/cli-body'
+import type { TelegramSendInput, TelegramTaskType } from './telegram-notify'
 
 /* eslint-disable @typescript-eslint/naming-convention */
 interface CliValues {

package/{scripts-ai → scripts/git}/telegram-test.ts

@@ -1,12 +1,12 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { parseArgs } from 'node:util'
-import { git_error } from '../scripts/git/git-error'
-import { git_gh_issue_read } from '../scripts/git/git-gh-issue-read'
-import { git_gh_repo } from '../scripts/git/git-gh-repo'
-import { github_issue_url, type IssueUrlTarget } from '../scripts/git/github-issue-url'
-import { telegram_notify } from '../scripts/git/telegram-notify'
-import { load_optional_environment } from './environment-loader'
+import { josh_environment_file } from '#scripts/josh/josh-environment-file'
+import { git_error } from './git-error'
+import { git_gh_issue_read } from './git-gh-issue-read'
+import { git_gh_repo } from './git-gh-repo'
+import { github_issue_url, type IssueUrlTarget } from './github-issue-url'
+import { telegram_notify } from './telegram-notify'
 import { telegram_test_logic, type CliValues, type ResolvedContext } from './telegram-test-logic'
 
 const REPO_NAME_SEPARATOR = '/'
@@ -97,7 +97,7 @@ async function resolve_context(values: CliValues): Promise<ResolvedContext> {
 }
 
 async function main(): Promise<void> {
-	load_optional_environment()
+	josh_environment_file.load_environment_file()
 	const values = parse_cli_arguments()
 	const context = await resolve_context(values)
 	const input = telegram_test_logic.build_input({ values, context })

package/scripts/hooks/format-rewrite-notice.ts

@@ -1,4 +1,4 @@
-import { readFileSync } from 'node:fs'
+import { file_reader } from '#scripts/lib/read-file'
 
 // The rewrite half of the edit hook (joshuafolkken/kit#2314). The format hook runs prettier and
 // `eslint --fix` in place after every edit, so a file the model just wrote can be rewritten out from
@@ -85,13 +85,7 @@ function build(before: string, after: string): string | undefined {
 // handed nothing for, or one gone by the time it reads, compares as an empty string rather than
 // throwing — the hook runs after the write already succeeded and must never turn it into a failure.
 function read_text(file_path: string | undefined): string {
-	if (file_path === undefined) return ''
-
-	try {
-		return readFileSync(file_path, 'utf8')
-	} catch {
-		return ''
-	}
+	return file_path === undefined ? '' : (file_reader.read_if_readable(file_path) ?? '')
 }
 
 const rewrite_notice = { build, read_text }

package/scripts/init/init-ai-copy.ts

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
 import { is_workflow_destination } from '#scripts/claude/workflow-destination'
 import { gh_spawn } from '#scripts/gh/gh-spawn'
+import { file_reader } from '#scripts/lib/read-file'
 import { managed_marker_logic } from '#scripts/managed-marker/managed-marker-logic'
 import {
 	classify_path,
@@ -238,11 +239,7 @@ function did_skip_ai_directory_copy(directory_name: string): boolean {
 // moved onto the basic path — only that kit-written line, never the consumer's additions.
 // An unreadable file is left as it is and reported as skipped, as it was before the migration.
 function read_if_readable(destination_path: string): string | undefined {
-	try {
-		return readFileSync(destination_path, 'utf8')
-	} catch {
-		return undefined
-	}
+	return file_reader.read_if_readable(destination_path)
 }
 
 function report_existing_claude_md(destination_path: string): void {

package/scripts/init/init.ts

@@ -4,6 +4,7 @@ import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { resolve_local_bin } from '#scripts/build/local-bin'
 import { doctor_io } from '#scripts/doctor/doctor-io'
+import { error_text } from '#scripts/lib/error-message'
 import { package_version_schema, with_package_manager_schema } from '#scripts/lib/schemas'
 import { auto_merge_setting } from '#scripts/repo/auto-merge-setting'
 import { project_config } from '#scripts/safe-chain/project-config'
@@ -45,8 +46,11 @@ function show_sample(action: FileAction): void {
 	console.info(action.create().replaceAll(/^/gmu, () => SAMPLE_INDENT))
 }
 
-function report_unchanged(action: FileAction): void {
-	if (action.should_show_sample_when_unchanged === true) show_sample(action)
+// A file that already holds the sample needs nothing added, so only one that differs gets it shown.
+function report_unchanged(action: FileAction, existing: string): void {
+	const is_sample_missing = existing !== action.create()
+
+	if (is_sample_missing && action.should_show_sample_when_unchanged === true) show_sample(action)
 	else console.info(`  ✔ unchanged ${action.dest}`)
 }
 
@@ -59,7 +63,7 @@ function merge_existing_file(
 	const merged = merge_function(existing)
 
 	if (merged === existing) {
-		report_unchanged(action)
+		report_unchanged(action, existing)
 
 		return
 	}
@@ -375,7 +379,7 @@ function run_cli(args: ReadonlyArray<string>): void {
 	try {
 		if (main(args)) print_start_hint()
 	} catch (error) {
-		console.error(`\n✖ ${error instanceof Error ? error.message : String(error)}\n`)
+		console.error(`\n✖ ${error_text.message_of(error)}\n`)
 		process.exitCode = 1
 	}
 }

package/scripts/init/start-steps.ts

@@ -1,4 +1,5 @@
 import path from 'node:path'
+import { error_text } from '#scripts/lib/error-message'
 import { repository_labels } from '#scripts/repo/repository-labels'
 import { self_sync_guard } from '#scripts/self-sync-guard/self-sync-guard-logic'
 import { main as init_main } from './init'
@@ -119,7 +120,7 @@ async function run_step(
 	try {
 		await STEP_ACTIONS[step](context)
 	} catch (error) {
-		const cause = error instanceof Error ? error.message : String(error)
+		const cause = error_text.message_of(error)
 
 		throw new Error(start_plan.progress_report(step, completed, cause), { cause: error })
 	}

package/scripts/init/start.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
+import { error_text } from '#scripts/lib/error-message'
 import { project_profile, type ProjectProfile } from './project-profile'
 import {
 	start_plan,
@@ -96,7 +97,7 @@ async function run(args: ReadonlyArray<string>, is_tty: boolean): Promise<number
 
 		return 0
 	} catch (error) {
-		console.error(error instanceof Error ? error.message : String(error))
+		console.error(error_text.message_of(error))
 
 		return 1
 	}

package/scripts/issue/issue-comment-cli.ts

@@ -2,6 +2,7 @@
 import { fileURLToPath } from 'node:url'
 import { git_gh_command } from '#scripts/git/git-gh-command'
 import { cli_body } from '#scripts/josh/cli-body'
+import { error_text } from '#scripts/lib/error-message'
 
 // `josh issue:comment <N> --body <text> | --body-file <path>` — post one comment to an issue (a PR
 // comment is an issue comment over REST) and print the comment URL (joshuafolkken/kit#2304).
@@ -66,7 +67,7 @@ function resolve_request(argv: ReadonlyArray<string>): CommentRequest | undefine
 
 		return request
 	} catch (error) {
-		console.error(error instanceof Error ? error.message : String(error))
+		console.error(error_text.message_of(error))
 
 		return undefined
 	}

package/scripts/issue/issue-file-cli.ts

@@ -7,6 +7,7 @@ import { git_gh_command } from '#scripts/git/git-gh-command'
 import { git_gh_exec } from '#scripts/git/git-gh-exec'
 import { git_gh_issue_write } from '#scripts/git/git-gh-issue-write'
 import { github_issue_url } from '#scripts/git/github-issue-url'
+import { error_text } from '#scripts/lib/error-message'
 import { issue_file, type FileArguments } from './issue-file'
 import { issue_lint_cli } from './issue-lint-cli'
 import { issue_scout_cli } from './issue-scout-cli'
@@ -105,7 +106,7 @@ async function create(filing: Filing): Promise<string | undefined> {
 	try {
 		return await git_gh_exec.exec_gh_api(request)
 	} catch (error) {
-		const reason = error instanceof Error ? error.message : String(error)
+		const reason = error_text.message_of(error)
 
 		console.error(`✖ the create call failed: ${reason}`)
 

package/scripts/issue/issue-fold-cli.ts

@@ -1,8 +1,8 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
-import { parseArgs } from 'node:util'
 import { git_command } from '#scripts/git/git-command'
 import { path_decision } from '#scripts/josh/path-decision'
+import { cli_flags } from '#scripts/lib/cli-flags'
 import { split_assess, type SplitVerdict } from '#scripts/split/split-assess'
 import { issue_fold, type FoldVerdict } from './issue-fold'
 
@@ -33,27 +33,20 @@ interface FoldArguments {
 	is_json: boolean
 }
 
-function parse_arguments(argv: ReadonlyArray<string>): FoldArguments {
-	const { values, positionals } = parseArgs({
+// An unknown flag is `undefined` rather than a throw, so the answer is the usage line rather than a
+// stack trace, on a command whose output a workflow reads.
+function read_arguments(argv: ReadonlyArray<string>): FoldArguments | undefined {
+	const parsed = cli_flags.parse_or_undefined({
 		args: [...argv],
 		options: { json: { type: 'boolean' }, 'not-separable': { type: 'boolean' } },
 		allowPositionals: true,
 	})
+	if (parsed === undefined) return undefined
 
 	return {
-		titles: positionals,
-		is_separable: values['not-separable'] !== true,
-		is_json: values.json === true,
-	}
-}
-
-// An unknown flag makes `parseArgs` throw. Caught so the answer is the usage line rather than a stack
-// trace, on a command whose output a workflow reads.
-function read_arguments(argv: ReadonlyArray<string>): FoldArguments | undefined {
-	try {
-		return parse_arguments(argv)
-	} catch {
-		return undefined
+		titles: parsed.positionals,
+		is_separable: parsed.values['not-separable'] !== true,
+		is_json: parsed.values.json === true,
 	}
 }
 

package/scripts/issue/issue-scout-cli.ts

@@ -1,12 +1,12 @@
 #!/usr/bin/env tsx
 import { readFile } from 'node:fs/promises'
 import { fileURLToPath } from 'node:url'
-import { parseArgs } from 'node:util'
 import { epic_audit_logic } from '#scripts/epic/epic-audit'
 import { epic_bundle, type BacklogIssue, type BundleDecision } from '#scripts/epic/epic-bundle'
 import { epic_bundle_cli } from '#scripts/epic/epic-bundle-cli'
 import { epic_bundle_gaps } from '#scripts/epic/epic-bundle-gaps'
 import { git_gh_command } from '#scripts/git/git-gh-command'
+import { cli_flags } from '#scripts/lib/cli-flags'
 import { issue_citation } from '#scripts/rules/issue-citation'
 import {
 	issue_scout,
@@ -59,12 +59,17 @@ function has_invalid_arguments(
 	)
 }
 
-function parse_arguments(argv: ReadonlyArray<string>): ScoutArguments | undefined {
-	const { values, positionals } = parseArgs({
+// An unknown flag is `undefined` rather than a throw, so the answer is the usage line rather than a
+// stack trace, on a command whose output a workflow reads.
+function read_arguments(argv: ReadonlyArray<string>): ScoutArguments | undefined {
+	const parsed = cli_flags.parse_or_undefined({
 		args: [...argv],
 		options: { body: { type: 'string' }, 'body-file': { type: 'string' } },
 		allowPositionals: true,
 	})
+	if (parsed === undefined) return undefined
+
+	const { values, positionals } = parsed
 	const [title] = positionals
 
 	if (has_invalid_arguments(title, values.body, values['body-file'])) return undefined
@@ -83,16 +88,6 @@ async function with_draft_body(args: ScoutArguments): Promise<ScoutArguments | u
 	}
 }
 
-// An unknown flag makes `parseArgs` throw. Caught so the answer is the usage line rather than a stack
-// trace, on a command whose output a workflow reads.
-function read_arguments(argv: ReadonlyArray<string>): ScoutArguments | undefined {
-	try {
-		return parse_arguments(argv)
-	} catch {
-		return undefined
-	}
-}
-
 // The issue as it would be filed. The summary is carried as the body because that is what the epic
 // half reads: the issue numbers its prose names are the references `decide_bundle` decides from.
 function draft_of(args: ScoutArguments, repo: string): BacklogIssue {

package/scripts/issue/measure-rerun-cli.ts

@@ -2,6 +2,7 @@
 import { execSync } from 'node:child_process'
 import { readFile } from 'node:fs/promises'
 import { fileURLToPath } from 'node:url'
+import { error_text } from '#scripts/lib/error-message'
 import { observation_ledger_home } from '#scripts/observations/observation-ledger-home'
 import { baseline_measure, type Baseline } from './baseline-measure'
 
@@ -21,7 +22,7 @@ function measure(command: string): string {
 	try {
 		return execSync(command, { encoding: 'utf8' }).trim()
 	} catch (error) {
-		return `(command failed: ${error instanceof Error ? error.message : String(error)})`
+		return `(command failed: ${error_text.message_of(error)})`
 	}
 }
 
@@ -40,12 +41,12 @@ function rerun_one(baseline: Baseline, date: string): Outcome {
 	}
 }
 
-async function append_ledger(lines: ReadonlyArray<string>): Promise<void> {
+async function append_ledger(lines: ReadonlyArray<string>, now: Date): Promise<void> {
 	if (lines.length === 0) return
 
-	// The primary checkout's ledger even inside a lane, whose own copy never reaches the default branch
-	// (joshuafolkken/kit#2419).
-	const ledger_path = observation_ledger_home.ledger_path()
+	// The running work tree's file for the checked-out issue, a lane's inside a lane — the run's own
+	// commit carries it (joshuafolkken/kit#2919).
+	const ledger_path = await observation_ledger_home.writer_path(now)
 
 	await observation_ledger_home.append(ledger_path, lines)
 	console.info(`Recorded ${String(lines.length)} refuted premise(s) in ${ledger_path}.`)
@@ -70,7 +71,7 @@ async function rerun(body_path: string, now: Date): Promise<number> {
 		.filter((line): line is string => line !== undefined)
 
 	console.info(outcomes.map((outcome) => outcome.pair).join('\n\n'))
-	await append_ledger(ledger_lines)
+	await append_ledger(ledger_lines, now)
 
 	return 0
 }

package/scripts/josh/josh-commands-ai.ts

@@ -27,7 +27,7 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 		reference: ['<message>', 'automation', ['git']],
 	},
 	epic: {
-		script: 'scripts-ai/epic.ts',
+		script: 'scripts/epic/epic.ts',
 		description: 'Create an epic issue from its child issue numbers',
 		category: 'AI tools',
 		reference: ['<title> <issue...> [--ordered]', 'automation', ['network']],
@@ -51,7 +51,7 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 		reference: ['<epic>', 'automation', ['network']],
 	},
 	'epic:check': {
-		script: 'scripts-ai/epic-check.ts',
+		script: 'scripts/epic/epic-check.ts',
 		description: 'Check an epic issue against the tracking requirements',
 		category: 'AI tools',
 		reference: ['<epic>', 'automation', ['network']],

package/scripts/josh/josh-commands-backlog.ts

@@ -19,7 +19,7 @@ const BACKLOG_COMMANDS: Record<string, CommandEntry> = {
 		description:
 			'Collapse a backlogrun loop-head event into one call: read backlog:next, ask backlog:budget, return the verdict and any issues to start',
 		category: 'AI tools',
-		reference: ['[options]', 'automation', ['network']],
+		reference: ['[options]', 'automation', ['files', 'network', 'processes']],
 	},
 	'backlog:drive': {
 		script: 'scripts/backlog/backlog-drive-cli.ts',

package/scripts/josh/josh-commands-development.ts

@@ -57,7 +57,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		description:
 			"Print each delivered rule's unaided compliance — runs reached, kept rate, refusals",
 		category: 'AI tools',
-		reference: ['', 'developer', ['none']],
+		reference: ['[--refresh]', 'developer', ['files']],
 	},
 	format: {
 		script: 'scripts/lint/format.ts',

package/scripts/josh/josh-commands-workflow.ts

@@ -1,6 +1,6 @@
 import { OPTIONAL_ENV_FILE_FLAGS, type CommandEntry } from './josh-command-types'
 
-const GIT_WORKFLOW_SCRIPT = 'scripts-ai/git-workflow.ts'
+const GIT_WORKFLOW_SCRIPT = 'scripts/git/git-workflow.ts'
 const GIT_MESSAGE_ARGUMENTS = '[-y] <message>'
 
 /* eslint-disable @typescript-eslint/naming-convention */
@@ -27,7 +27,7 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 	// session, and `followup` with them the merge step of every `fullrun` there. `doctor` was moved to
 	// this form for the same reason in joshuafolkken/kit#869.
 	//
-	// Nothing is lost by relaxing it: both scripts already call `load_optional_environment()`
+	// Nothing is lost by relaxing it: both scripts already load `.env` through `josh_environment_file`
 	// themselves, so the file is read either way and node's precedence — an existing environment
 	// variable wins over the file — is node's own in both spellings.
 	//
@@ -35,7 +35,7 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 	// than dropped: `telegram_notify.send` now throws on missing credentials and on a failed send, so
 	// `josh notify` exits non-zero instead of warning and answering 0.
 	followup: {
-		script: 'scripts-ai/git-followup-workflow.ts',
+		script: 'scripts/git/git-followup-workflow.ts',
 		description: 'Follow-up git workflow',
 		category: 'Workflow',
 		reference: [
@@ -46,7 +46,7 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
 	},
 	notify: {
-		script: 'scripts-ai/telegram-test.ts',
+		script: 'scripts/git/telegram-test.ts',
 		description: 'Send Telegram notification',
 		category: 'Workflow',
 		reference: ['--task-type <type> --body <text>', 'automation', ['notifications']],

package/scripts/lane/lane-cli.ts

@@ -2,6 +2,7 @@
 import { fileURLToPath } from 'node:url'
 import { epic_busy } from '#scripts/epic/epic-busy'
 import { git_gh_command } from '#scripts/git/git-gh-command'
+import { error_text } from '#scripts/lib/error-message'
 import { run_carry } from '#scripts/run/run-carry'
 import { lane_await } from './lane-await'
 import { lane_close, type CloseOutcome, type SweepOutcome } from './lane-close'
@@ -384,7 +385,7 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 	try {
 		return await dispatch(argv)
 	} catch (error) {
-		console.error(error instanceof Error ? error.message : String(error))
+		console.error(error_text.message_of(error))
 
 		return FAILURE_EXIT_CODE
 	}

package/scripts/lane/lane-open.ts

@@ -1,7 +1,8 @@
-import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
 import { ENV_FILE_NAME } from '#ports'
 import { git_worktree } from '#scripts/git/git-worktree'
+import { file_reader } from '#scripts/lib/read-file'
 import { lane_cache } from './lane-cache'
 import { lane_environment } from './lane-environment'
 import { lane_install, type InstallResult } from './lane-install'
@@ -52,7 +53,7 @@ const SEAT_LOCK_PREFIX = 'seat-'
 function read_root_environment(repository_root: string): string {
 	const file = path.join(repository_root, ENV_FILE_NAME)
 
-	return existsSync(file) ? readFileSync(file, 'utf8') : ''
+	return file_reader.read_file_or_empty(file)
 }
 
 function build_lane(

package/scripts/lane/lane-registry.ts

@@ -1,10 +1,11 @@
-import { existsSync, readFileSync } from 'node:fs'
+import { existsSync } from 'node:fs'
 import path from 'node:path'
 import { ENV_FILE_NAME } from '#ports'
 import type { AgentProfile } from '#scripts/agent/agent-role-profile'
 import { repo_discovery } from '#scripts/discovery/repo-discovery'
 import { git_command } from '#scripts/git/git-command'
 import { git_worktree } from '#scripts/git/git-worktree'
+import { file_reader } from '#scripts/lib/read-file'
 import { lane_environment } from './lane-environment'
 import { lane_paths } from './lane-paths'
 
@@ -105,11 +106,7 @@ function held_seat(content: string | undefined): SeatPorts {
  * a state the report shows rather than a state anything falls back from.
  */
 function read_environment(directory: string): string | undefined {
-	try {
-		return readFileSync(path.join(directory, ENV_FILE_NAME), 'utf8')
-	} catch {
-		return undefined
-	}
+	return file_reader.read_if_readable(path.join(directory, ENV_FILE_NAME))
 }
 
 // A lane is identified by its branch rather than by where it sits, so nothing here compares two

package/scripts/lib/cli-flags.ts

@@ -1,4 +1,6 @@
-// Argument refusal for the small flag-only commands.
+import { parseArgs, type ParseArgsConfig } from 'node:util'
+
+// Argument reading for the commands under `scripts/`.
 //
 // Reject anything not on the list rather than ignoring it: a misspelled `--dryrun` that fell through
 // would run the real write path. `josh propagate` and `josh adopt` both write into working trees, so
@@ -16,4 +18,20 @@ function refuse_unknown_flags(
 	return `Unknown argument(s): ${unknown.join(' ')}\n${usage}`
 }
 
-export { refuse_unknown_flags }
+// `parseArgs`, answering `undefined` where it would throw — an unknown flag, a missing option value,
+// or a positional the config does not allow. Each caller turns that into its usage line and a failure
+// exit rather than a stack trace, on commands whose output a workflow reads; eleven of them had begun
+// to carry a copy of the same try/catch each (joshuafolkken/kit#2902), and this is the one copy.
+function parse_or_undefined<T extends ParseArgsConfig>(
+	config: T,
+): ReturnType<typeof parseArgs<T>> | undefined {
+	try {
+		return parseArgs(config)
+	} catch {
+		return undefined
+	}
+}
+
+const cli_flags = { refuse_unknown_flags, parse_or_undefined }
+
+export { cli_flags }

package/scripts/lib/error-message.ts

@@ -0,0 +1,9 @@
+// The one place a caught value becomes the text a report shows: an `Error` contributes its own message,
+// anything else thrown is stringified as it stands.
+function message_of(error: unknown): string {
+	return error instanceof Error ? error.message : String(error)
+}
+
+const error_text = { message_of }
+
+export { error_text }

package/scripts/lib/read-file.ts

@@ -1,16 +1,40 @@
 import { readFileSync } from 'node:fs'
 
+const ABSENT_CODE = 'ENOENT'
+
+function is_absent(error: unknown): boolean {
+	return error instanceof Error && 'code' in error && error.code === ABSENT_CODE
+}
+
+// An absent file is an answer ("nothing declared here"); any other failure — a permission error, a
+// directory where a file was expected — is not, and is thrown so it cannot pass for an empty file.
+function read_optional(path: string): string | undefined {
+	try {
+		return readFileSync(path, 'utf8')
+	} catch (error) {
+		if (is_absent(error)) return undefined
+
+		throw error
+	}
+}
+
 // Several readers treat an absent file as "nothing declared" rather than an error: a project may
 // carry no lockfile yet, and either overrides location may be missing entirely. Empty content is
 // the shared stand-in, so the callers do not each re-implement the try/catch.
 function read_file_or_empty(path: string): string {
+	return read_optional(path) ?? ''
+}
+
+// For a reader whose contract is to never fail — a hook running after a write already succeeded, a
+// report that states "unreadable" itself — every failure to read, not only absence, is `undefined`.
+function read_if_readable(path: string): string | undefined {
 	try {
 		return readFileSync(path, 'utf8')
 	} catch {
-		return ''
+		return undefined
 	}
 }
 
-const file_reader = { read_file_or_empty }
+const file_reader = { read_optional, read_file_or_empty, read_if_readable }
 
 export { file_reader }