@joshuafolkken/kit 1.1005.0 → 1.1035.0

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-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))
 	}
 }
 

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

@@ -1,4 +1,4 @@
-import { parseArgs } from 'node:util'
+import { cli_flags } from '#scripts/lib/cli-flags'
 import { run_progress_config } from './run-progress-config'
 
 // The argument half of `josh run:progress`, kept apart from the watcher so the CLI stays inside the file
@@ -37,11 +37,7 @@ interface ParsedValues {
 }
 
 function read_arguments(argv: ReadonlyArray<string>): ParsedValues | undefined {
-	try {
-		return parseArgs({ args: [...argv], options: OPTIONS }).values
-	} catch {
-		return undefined
-	}
+	return cli_flags.parse_or_undefined({ args: [...argv], options: OPTIONS })?.values
 }
 
 // A hand-typed `--interval` outranks the environment, the environment outranks the interval the

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

@@ -5,6 +5,7 @@ import { backlog_arrival, type ArrivalProbe } from '#scripts/backlog/backlog-arr
 import { backlog_ready } from '#scripts/backlog/backlog-ready'
 import { gh_spawn } from '#scripts/gh/gh-spawn'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
+import { error_text } from '#scripts/lib/error-message'
 import { run_event_stream_emit } from './run-event-stream-emit'
 import { run_progress, type ProgressState } from './run-progress'
 import { run_progress_args, type ParsedValues } from './run-progress-args'
@@ -229,7 +230,7 @@ function decline(loop: WatchLoop, now_ms: number, notice: string): WatchLoop {
 // under load — the very load this command exists to report — would otherwise take the reporting down
 // silently for the rest of an unattended run, with the parent not waiting on it and nothing saying why.
 function to_notice(error: unknown): string {
-	return `${FAILED_TICK_PREFIX} ${error instanceof Error ? error.message : String(error)}`
+	return `${FAILED_TICK_PREFIX} ${error_text.message_of(error)}`
 }
 
 async function attempt(

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

@@ -17,9 +17,9 @@ import { run_tail, type TailSection } from './run-tail'
 //
 // **A dispatched lane child skips the ledger step** (joshuafolkken/kit#2492). A flush opens a
 // ledger-only pull request and waits out its whole CI before it merges — minutes per issue, spent on a
-// file only the retrospective and the measurements read. The line stays appended in the primary
-// checkout, and the `backlogrun` parent flushes once at its end (`run:carry --end`, `run-carry-flush.ts`).
-// A single run outside a lane keeps the step: its one end is already the run's end.
+// file only the retrospective and the measurements read — and a lane has nothing for it: its lines
+// merged with its own pull request (joshuafolkken/kit#2919). A single run outside a lane keeps the
+// step for a line written on the default branch outside any issue's run.
 
 const ARGV_OFFSET = 2
 const SUCCESS_EXIT_CODE = 0

package/scripts/run/run-tidy-stashes.ts

@@ -1,4 +1,3 @@
-import { readFile } from 'node:fs/promises'
 import { git_stash, type StashEntry } from '#scripts/git/git-stash'
 import { stash_orphans } from '#scripts/git/stash-orphans'
 import { stash_sweep_lock } from '#scripts/git/stash-sweep-lock'
@@ -18,16 +17,8 @@ const READ_CONCURRENCY = 8
 const GONE_REASON = 'already dropped by another run'
 const BUSY_REASON = 'another run held the stash sweep lock'
 
-async function read_ledger(ledger_path: string): Promise<string> {
-	try {
-		return await readFile(ledger_path, 'utf8')
-	} catch {
-		return ''
-	}
-}
-
-// An entry cut before joshuafolkken/kit#2724 holds its lines at the ledger's old path, so the lines of
-// every ledger path it touches are carried to the current ledger.
+// An entry cut before joshuafolkken/kit#2919 holds its lines at an old single-file path, so the lines
+// of every ledger path it touches are carried to the current ledger.
 async function added_ledger_lines(
 	hash: string,
 	ledger_paths: ReadonlyArray<string>,
@@ -43,16 +34,18 @@ async function added_ledger_lines(
 	return added
 }
 
-// How many ledger lines went into the primary checkout's ledger before the drop.
+// How many ledger lines went into the running work tree's ledger before the drop. The duplicate check
+// reads every issue's file, and the lines land in the file this tree writes (joshuafolkken/kit#2919),
+// so the run's own commit takes them to the default branch.
 async function carry_ledger(hash: string): Promise<number> {
 	const changed = await git_stash.changed_paths(hash)
 	const ledger_paths = changed.filter((file_path) => observation_ledger.is_ledger_path(file_path))
 
 	if (ledger_paths.length === 0) return 0
 
-	const ledger_path = observation_ledger_home.ledger_path()
+	const ledger_path = await observation_ledger_home.writer_path(new Date())
 	const added = await added_ledger_lines(hash, ledger_paths)
-	const carried = run_tidy.ledger_carry(added, await read_ledger(ledger_path))
+	const carried = run_tidy.ledger_carry(added, (await observation_ledger_home.read()) ?? '')
 
 	await observation_ledger_home.append(ledger_path, carried)
 

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

@@ -2,9 +2,9 @@
 import { randomUUID } from 'node:crypto'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { parseArgs } from 'node:util'
 import type { AgentProfile } from '#scripts/agent/agent-role-profile'
 import { telegram_notify } from '#scripts/git/telegram-notify'
+import { cli_flags } from '#scripts/lib/cli-flags'
 import { run_carry, type CarryRead } from './run-carry'
 import { run_event_stream } from './run-event-stream'
 import { run_headless } from './run-headless'
@@ -120,11 +120,7 @@ function note_to_stderr(note: string): void {
 }
 
 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: string | boolean | undefined): string | undefined {

package/scripts/run/run-wake-driver.ts

@@ -6,6 +6,8 @@ import type { DriveResult } from './run-wake-loop'
 const SUCCESS = 0
 const FIRST_LINE = 0
 const RESUME_PREFIX = 'resume: '
+const DETAILS_TAIL_LENGTH = 2048
+const TRUNCATION_MARK = '... '
 
 function driver_args(invocation: string): ReadonlyArray<string> | undefined {
 	const rebuilt = run_invocation.rebuild(invocation)
@@ -24,13 +26,24 @@ function is_final_stop(verdict: string | undefined, read: CarryRead): boolean {
 	return verdict?.startsWith('stop') === true && read.kind === 'none'
 }
 
+// **The details are the driver's whole stderr, so only their tail is handed on, and it goes last**
+// (joshuafolkken/kit#2931). The stderr carries every command the driver ran since it started, which
+// after a long run is tens of kilobytes — far past what `is_safe_value` lets into an argv element. Its
+// tail is where the reason for stopping is; placing it last means the cap `wake_argv` applies to the
+// whole prompt can only ever cut into the details, never the verdict, the resume line or the epic note.
+function details_tail(details: string): string {
+	return details.length > DETAILS_TAIL_LENGTH
+		? `${TRUNCATION_MARK}${details.slice(-DETAILS_TAIL_LENGTH)}`
+		: details
+}
+
 function handoff_material(verdict: string, resume: string, details: string): string {
-	const context = details === '' ? '' : `\nDetails: ${details}`
+	const context = details === '' ? '' : `\nDetails: ${details_tail(details)}`
 	const epic = verdict.startsWith('epic #')
 		? '\nThe named item is an epic. Follow backlogrun-steps.md named epic procedure; do not launch the epic root as a fullrun child. After all children merge or park, record the root with pnpm josh run:carry --done <epic-number> --owner "$PPID" before continuing to the next named item.'
 		: ''
 
-	return `Driver result: ${verdict}\n${resume}${context}${epic}`
+	return `Driver result: ${verdict}\n${resume}${epic}${context}`
 }
 
 function driver_result(out: string, read: CarryRead, details = ''): DriveResult {

package/scripts/run/run-wake-session.ts

@@ -37,6 +37,8 @@ const WAKE_FLAGS = claude_agent_argv.AGENT_FLAGS
 const LOOP_FLAG = '--loop'
 const INTERVAL_FLAG = '--interval'
 const SUPERVISOR_SESSION = 'run-wake-supervisor'
+// eslint-disable-next-line no-control-regex -- matching control characters is the point
+const CONTROL_CHARACTERS = /[\u{0}-\u{1F}\u{7F}]/gu
 
 function scheduler_profile(): AgentProfile | undefined {
 	const resolved = agent_role_profile.resolve(agent_role_profile.SCHEDULER)
@@ -96,6 +98,17 @@ function resolved_argv(invocation: string, cwd?: string): AgentArgvResult {
 		: agent_argv.resolve_in(invocation, agent_role_profile.SCHEDULER, cwd)
 }
 
+// **Handoff material is made safe to launch rather than refused** (joshuafolkken/kit#2931). It is the
+// driver's own output, not the record, so it is flattened — a newline becomes a separator, any other
+// control character a space — and the prompt is cut at the cap `is_safe_value` enforces. The driver puts
+// its verdict and resume line first, so the cut only ever shortens the details. The check itself is
+// untouched: the argv still passes `is_safe_argv` before anything is spawned.
+function handoff_prompt(matched: string, material: string): string {
+	const flattened = material.replaceAll('\n', ' | ').replaceAll(CONTROL_CHARACTERS, ' ')
+
+	return `${matched} | Driver handoff: ${flattened}`.slice(0, agent_role_profile.MAX_VALUE_LENGTH)
+}
+
 function wake_argv(
 	invocation: string,
 	profile?: AgentProfile,
@@ -104,10 +117,7 @@ function wake_argv(
 ): AgentArgvResult | undefined {
 	const matched = safe_invocation(invocation)
 	if (matched === undefined) return undefined
-	const prompt =
-		typeof session === 'object'
-			? `${matched} | Driver handoff: ${session.material.replaceAll('\n', ' | ')}`
-			: matched
+	const prompt = typeof session === 'object' ? handoff_prompt(matched, session.material) : matched
 	const session_id = typeof session === 'object' ? session.id : session
 
 	return profile === undefined

package/scripts/safe-chain/project-config.ts

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
+import { file_reader } from '#scripts/lib/read-file'
 import { release_age } from '#scripts/version/release-age'
 import { yaml_document } from '#scripts/yaml/yaml-document'
 import { dump } from 'js-yaml'
@@ -126,17 +127,13 @@ function merge_project_config(existing: string, workspace: string, npmrc = ''):
 	return replace_safe_chain_block(existing, merged)
 }
 
-function read_optional(file_path: string): string {
-	return existsSync(file_path) ? readFileSync(file_path, 'utf8') : ''
-}
-
 function sync_project_config(root: string): boolean {
 	const workspace_path = path.join(root, WORKSPACE_FILE)
 	if (!existsSync(workspace_path)) return false
 	const config_path = path.join(root, PROJECT_CONFIG_FILE)
-	const existing = read_optional(config_path)
+	const existing = file_reader.read_file_or_empty(config_path)
 	const workspace = readFileSync(workspace_path, 'utf8')
-	const npmrc = read_optional(path.join(root, NPMRC_FILE))
+	const npmrc = file_reader.read_file_or_empty(path.join(root, NPMRC_FILE))
 	const merged = merge_project_config(existing, workspace, npmrc)
 	if (merged === existing) return false
 	writeFileSync(config_path, merged)

package/scripts/security/security-audit-provision.ts

@@ -4,6 +4,7 @@ import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
 import { stamp_file } from '#scripts/josh/stamp-file'
+import { error_text } from '#scripts/lib/error-message'
 import { security_audit } from './security-audit'
 import { security_audit_logic } from './security-audit-logic'
 import { security_audit_provision_logic, type ScannerAsset } from './security-audit-provision-logic'
@@ -14,10 +15,6 @@ const FORCE_FLAG = '--force'
 const PATH_LOCATION = 'on PATH'
 const { RETRY_INTERVAL_MS } = security_audit_provision_logic
 
-function describe_error(error: unknown): string {
-	return error instanceof Error ? error.message : String(error)
-}
-
 // `content` absent is the failure, and `reason` says which one. A 404 — what a bumped version whose
 // asset was renamed looks like, and the one failure that never fixes itself — would otherwise read
 // exactly like a transient 503, and a rejected request like neither.
@@ -41,7 +38,7 @@ async function download(url: string, timeout_ms: number): Promise<DownloadOutcom
 
 		return { content: Buffer.from(await response.arrayBuffer()), reason: '' }
 	} catch (error) {
-		return { reason: describe_error(error) }
+		return { reason: error_text.message_of(error) }
 	}
 }
 
@@ -128,7 +125,7 @@ async function attempt(
 	} catch (error) {
 		return record_failure(
 			target_path,
-			security_audit_provision_logic.format_provision_error(describe_error(error)),
+			security_audit_provision_logic.format_provision_error(error_text.message_of(error)),
 		)
 	}
 }
@@ -175,7 +172,9 @@ async function main(): Promise<void> {
 	try {
 		console.info(await report(PROJECT_ROOT, process.platform, process.arch, is_forced))
 	} catch (error) {
-		console.warn(security_audit_provision_logic.format_provision_error(describe_error(error)))
+		console.warn(
+			security_audit_provision_logic.format_provision_error(error_text.message_of(error)),
+		)
 	}
 }
 

package/scripts/sonar/sonar-hotspots-cli.ts

@@ -3,6 +3,7 @@ import { existsSync, readFileSync } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { git_command } from '#scripts/git/git-command'
+import { error_text } from '#scripts/lib/error-message'
 import { managed_config_scope } from '#scripts/sync/managed-config-scope'
 import { z } from 'zod'
 import {
@@ -69,7 +70,7 @@ async function fetch_hotspots(url: string): Promise<HotspotFetch> {
 
 		return { hotspots: parsed.hotspots ?? [] }
 	} catch (error) {
-		return { error: error instanceof Error ? error.message : String(error) }
+		return { error: error_text.message_of(error) }
 	}
 }
 

package/scripts/sync/directory-copy-guard.ts

@@ -1,6 +1,7 @@
 import { cpSync, lstatSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
 import { transform_copied_content } from '#scripts/init/init-copy-content'
+import { error_text } from '#scripts/lib/error-message'
 import { file_content } from './file-content'
 
 // `josh init` and `josh sync` both copy a distributed directory with `cpSync`, and both have to
@@ -143,7 +144,7 @@ function copy_directory(source_path: string, destination_path: string): boolean
 // throw here would end `josh init` or `josh sync` in the middle of their work. The message is
 // returned for the caller to report, the same way a blocker is.
 function failure_message(prefix: string, error: unknown): string {
-	return `${prefix} (${error instanceof Error ? error.message : String(error)})`
+	return `${prefix} (${error_text.message_of(error)})`
 }
 
 // The two failures are reported apart because they leave the destination in opposite states, and

package/scripts/sync/sync-ai-files.ts

@@ -5,6 +5,7 @@ import { transform_copied_content } from '#scripts/init/init-copy-content'
 import { init_logic } from '#scripts/init/init-logic'
 import { PACKAGE_DIR, PROJECT_ROOT } from '#scripts/init/init-paths'
 import type { ProjectShape } from '#scripts/init/project-profile'
+import { file_reader } from '#scripts/lib/read-file'
 import { copy_directory_failure, directory_copy_blocker } from './directory-copy-guard'
 import { file_content } from './file-content'
 import { REMOVED_SKILL_MANIFEST } from './removed-skill-manifest'
@@ -70,8 +71,7 @@ function sync_workspace_yaml(
 	is_force = false,
 ): boolean {
 	const template = readFileSync(template_path, 'utf8')
-	const existing =
-		!is_force && existsSync(destination_path) ? readFileSync(destination_path, 'utf8') : ''
+	const existing = is_force ? '' : file_reader.read_file_or_empty(destination_path)
 	const merged = init_logic.merge_workspace_yaml(existing, template)
 
 	return file_content.write_text_if_changed(destination_path, merged)
@@ -155,7 +155,7 @@ function ensured_claude_md(existing: string | undefined, shape?: ProjectShape):
 // without ever disturbing those additions — so this ignores --force, which would otherwise mean
 // discarding a consumer's content.
 function sync_claude_md(destination_path: string, shape?: ProjectShape): void {
-	const existing = existsSync(destination_path) ? readFileSync(destination_path, 'utf8') : undefined
+	const existing = file_reader.read_optional(destination_path)
 	const ensured = ensured_claude_md(existing, shape)
 
 	if (ensured === existing) {

package/scripts/sync/template-source-logic.ts

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto'
-import { copyFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { copyFileSync, readFileSync, writeFileSync } from 'node:fs'
 import { package_path } from '#scripts/init/init-paths'
+import { file_reader } from '#scripts/lib/read-file'
 import { z } from 'zod'
 
 interface TemplateSourcePair {
@@ -39,9 +40,7 @@ function read_file(relative_path: string): string {
 }
 
 function read_optional_file(relative_path: string): string {
-	const full_path = package_path(relative_path)
-
-	return existsSync(full_path) ? readFileSync(full_path, 'utf8') : ''
+	return file_reader.read_file_or_empty(package_path(relative_path))
 }
 
 function hash_text(text: string): string {

package/scripts/test/e2e-retry-check.ts

@@ -1,7 +1,8 @@
 #!/usr/bin/env tsx
-import { appendFileSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { appendFileSync, readdirSync, statSync } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { file_reader } from '#scripts/lib/read-file'
 
 // Whether the preview server process died during a failed E2E attempt.
 //
@@ -59,11 +60,7 @@ function has_crash_signature(log_text: string): boolean {
 }
 
 function read_file_safe(file_path: string): string {
-	try {
-		return readFileSync(file_path, 'utf8')
-	} catch {
-		return ''
-	}
+	return file_reader.read_if_readable(file_path) ?? ''
 }
 
 // Every file under the directory, because wrangler names the debug log after the run and a job that

package/scripts/ui/ui-routes-cli.ts

@@ -1,9 +1,10 @@
 #!/usr/bin/env tsx
-import { readdirSync, readFileSync } from 'node:fs'
+import { readdirSync } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { changed_paths } from '#scripts/git/changed-paths'
 import { git_command } from '#scripts/git/git-command'
+import { file_reader } from '#scripts/lib/read-file'
 import { ui_routes } from './ui-routes'
 
 // `josh ui:routes [--staged]` — list the screenshot-target routes the current change touches
@@ -59,11 +60,7 @@ function route_files(root: string): Array<RouteFile> {
 }
 
 function read_text(file: string): string {
-	try {
-		return readFileSync(file, 'utf8')
-	} catch {
-		return ''
-	}
+	return file_reader.read_if_readable(file) ?? ''
 }
 
 // A route file imports the component when its source names the component's file — the import

package/scripts/version/bump-version.ts

@@ -2,6 +2,7 @@
 import { readFileSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { error_text } from '#scripts/lib/error-message'
 import { json_object_schema, package_with_version_schema } from '#scripts/lib/schemas'
 import semver from 'semver'
 
@@ -61,7 +62,7 @@ function main(): void {
 	try {
 		bump_version(bump_type as BumpType)
 	} catch (error) {
-		console.error(error instanceof Error ? error.message : String(error))
+		console.error(error_text.message_of(error))
 		process.exit(1)
 	}
 }

package/scripts/version/version-remote.ts

@@ -1,9 +1,8 @@
 import { git_gh_exec } from '#scripts/git/git-gh-exec'
-import { execaSync } from 'execa'
+import { error_text } from '#scripts/lib/error-message'
 import { safe_json_parse } from './parse-json'
 import { release_age } from './release-age'
 
-const GH_FAILURE_FALLBACK = 'gh api failed'
 // Enough history to reach past a quarantine window into the newest release that has aged out of it.
 // The endpoint's default page is a single entry, so it is widened to the API's maximum rather than
 // paged through: a page that cannot span the window resolves no aged release at all, which silently
@@ -23,32 +22,27 @@ function require_endpoint(versions_endpoint: string | undefined, package_name: s
 	)
 }
 
-// Turn a failed `gh api` result into a concise detail line: prefer gh's own stderr
-// (e.g. "gh: Not Found (HTTP 404)"), falling back to execa's short message.
-function describe_failure(result: { stderr: string; shortMessage?: string | undefined }): string {
-	const stderr = result.stderr.trim()
-
-	if (stderr !== '') return stderr
-
-	return result.shortMessage ?? GH_FAILURE_FALLBACK
-}
-
 // Fetch the latest published version from a GitHub Packages versions endpoint. The endpoint is
 // supplied per package (e.g. `/users/joshuafolkken/packages/npm/kit/versions?per_page=1`) so the
 // same fetcher serves kit, jgame, and app-kit. Guards an undefined/empty endpoint and wraps
-// `gh api` failures with an actionable message instead of a raw ExecaSyncError stack.
+// `gh api` failures with an actionable message instead of a raw ExecaSyncError stack. The detail is
+// the shared layer's failure text: gh's own stderr (e.g. "gh: Not Found (HTTP 404)") when it wrote
+// one, execa's message otherwise, followed by any JSON error body gh wrote to stdout.
 function fetch_latest_version(versions_endpoint: string | undefined, package_name: string): string {
 	const endpoint = require_endpoint(versions_endpoint, package_name)
-	const result = execaSync('gh', ['api', endpoint, '--jq', '.[0].name'], {
-		...git_gh_exec.direct_environment(),
-		reject: false,
-	})
 
-	if (result.exitCode === 0) return result.stdout.trim()
+	try {
+		return git_gh_exec.exec_gh_api_sync({ path: endpoint, jq_filter: '.[0].name' }).trim()
+	} catch (error) {
+		const detail = error_text.message_of(error)
 
-	throw new Error(
-		`Failed to fetch latest version for ${package_name} via ${endpoint}: ${describe_failure(result)}`,
-	)
+		throw new Error(
+			`Failed to fetch latest version for ${package_name} via ${endpoint}: ${detail}`,
+			{
+				cause: error,
+			},
+		)
+	}
 }
 
 // Rewrite the endpoint's page size. The endpoint is consumer-overridable, so `per_page` is set
@@ -73,12 +67,9 @@ function fetch_release_times(
 ): Record<string, string> | undefined {
 	if (versions_endpoint === undefined || versions_endpoint.trim() === '') return undefined
 	const endpoint = with_page_size(versions_endpoint, TIMES_PAGE_SIZE)
-	const result = execaSync('gh', ['api', endpoint, '--jq', TIMES_JQ], {
-		...git_gh_exec.direct_environment(),
-		reject: false,
-	})
-	if (result.exitCode !== 0) return undefined
-	const parsed = release_age.release_times_schema.safeParse(safe_json_parse(result.stdout))
+	const stdout = git_gh_exec.read_gh_api_sync({ path: endpoint, jq_filter: TIMES_JQ })
+	if (stdout === undefined) return undefined
+	const parsed = release_age.release_times_schema.safeParse(safe_json_parse(stdout))
 
 	return parsed.success ? parsed.data : undefined
 }

package/scripts/version/version-targets.ts

@@ -1,5 +1,5 @@
-import { existsSync, readFileSync } from 'node:fs'
 import path from 'node:path'
+import { file_reader } from '#scripts/lib/read-file'
 import { package_version_schema, pnpm_ls_global_schema } from '#scripts/lib/schemas'
 import { execaSync } from 'execa'
 import { safe_json_parse } from './parse-json'
@@ -42,7 +42,7 @@ function project_package_path(cwd: string, package_name: string): string {
 
 function read_project_version(cwd: string, package_name: string): string | undefined {
 	const package_path = project_package_path(cwd, package_name)
-	const raw = existsSync(package_path) ? readFileSync(package_path, 'utf8') : undefined
+	const raw = file_reader.read_optional(package_path)
 
 	return parse_project_version(raw)
 }
@@ -52,7 +52,7 @@ function read_project_version(cwd: string, package_name: string): string | undef
 // package version under node_modules.
 function read_workspace_version(cwd: string): string | undefined {
 	const package_path = path.join(cwd, PACKAGE_JSON)
-	const raw = existsSync(package_path) ? readFileSync(package_path, 'utf8') : undefined
+	const raw = file_reader.read_optional(package_path)
 
 	return parse_project_version(raw)
 }