@joshuafolkken/kit 1.1514.0 → 1.1784.0

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

@@ -1,7 +1,6 @@
-import { readFileSync } from 'node:fs'
-import path from 'node:path'
 import { ancestor_directories } from '#scripts/lib/ancestor-directories'
-import { json_value } from '#scripts/lib/json-value'
+import { PACKAGE_JSON, package_manifest } from '#scripts/lib/package-manifest'
+import { MS_PER_MINUTE } from '#scripts/lib/timeouts'
 import { z } from 'zod'
 import { run_progress } from './run-progress'
 
@@ -25,8 +24,6 @@ import { run_progress } from './run-progress'
 // Reading the working directory alone would let the guard enforce the repository's interval while the
 // watcher it guards kept the default, which is the one state this module exists to prevent.
 
-const PACKAGE_FILE = 'package.json'
-
 // Unknown keys are stripped rather than rejected: this reads a whole `package.json`, and every other
 // field in it is none of this module's business. A present-but-unusable interval fails the parse and
 // falls through, which is the same answer an unusable environment variable already gets.
@@ -35,13 +32,8 @@ const package_schema = z.object({
 })
 
 function read_declared_minutes(directory: string): number | undefined {
-	try {
-		const raw = readFileSync(path.join(directory, PACKAGE_FILE), 'utf8')
-
-		return json_value.parse_with(raw, package_schema)?.josh?.progress_interval_minutes
-	} catch {
-		return undefined
-	}
+	return package_manifest.read_manifest_if_valid(directory, package_schema)?.josh
+		?.progress_interval_minutes
 }
 
 function read_package_minutes(start: string): number | undefined {
@@ -55,7 +47,7 @@ function read_package_minutes(start: string): number | undefined {
 }
 
 function to_ms(minutes: number | undefined): number | undefined {
-	return minutes === undefined ? undefined : minutes * run_progress.MS_PER_MINUTE
+	return minutes === undefined ? undefined : minutes * MS_PER_MINUTE
 }
 
 /**
@@ -88,7 +80,7 @@ function configured_interval_ms(directory: string = process.cwd()): number {
 }
 
 const run_progress_config = {
-	PACKAGE_FILE,
+	PACKAGE_FILE: PACKAGE_JSON,
 	configured_interval_ms,
 	read_package_minutes,
 	resolve_interval_ms,

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

@@ -0,0 +1,12 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { run_progress_cli } from './run-progress-cli'
+
+// The `josh run:progress` entry, kept apart from `run-progress-cli.ts` because other modules import
+// that one: a bundle is one file, so a main guard there would fire for every command that carries it
+// (joshuafolkken/kit#4186).
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const ARGV_OFFSET = 2
+
+	process.exitCode = await run_progress_cli.run(process.argv.slice(ARGV_OFFSET))
+}

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

@@ -1,4 +1,5 @@
 import { issue_cite, type IssueCiter } from '#scripts/issue/issue-cite'
+import { MS_PER_MINUTE } from '#scripts/lib/timeouts'
 
 // `josh run:progress` — the one line an unattended run prints when it has gone quiet, and the clock
 // that decides when that is.
@@ -45,8 +46,6 @@ const DEFAULT_INTERVAL_MINUTES = 20
 // The one name for the setting, so the watcher and the guard read the same variable rather than two
 // spellings of it.
 const INTERVAL_KEY = 'JOSH_PROGRESS_INTERVAL_MINUTES'
-const MS_PER_MINUTE = 60_000
-const MS_PER_SECOND = 1000
 const DEFAULT_INTERVAL_MS = DEFAULT_INTERVAL_MINUTES * MS_PER_MINUTE
 // The switch that silences every progress report — the watcher's and `run:board --every`'s alike.
 const DISABLED_KEY = 'JOSH_PROGRESS'
@@ -351,8 +350,6 @@ const run_progress = {
 	DISABLED_KEY,
 	DISABLED_VALUE,
 	INTERVAL_KEY,
-	MS_PER_MINUTE,
-	MS_PER_SECOND,
 	NO_CHILD_YET,
 	NO_NEXT,
 	format_child,

package/scripts/run/review/run-review.ts

@@ -11,6 +11,8 @@
 // - **how far the gate and the review overlapped** — the measurement the parallel start exists to
 //   produce, computed from the four timestamps `run-review-steps.ts` records.
 
+import { MS_PER_SECOND } from '#scripts/lib/timeouts'
+
 const ADOPT = 'adopt'
 const BLOCKED = 'blocked'
 
@@ -46,7 +48,6 @@ function is_gate_settled(state: GateState): boolean {
 	return state !== GATE_RUNNING
 }
 
-const MS_PER_SECOND = 1000
 const SECONDS_DECIMALS = 1
 const NO_OVERLAP = 0
 

package/scripts/run/run-ending.ts

@@ -246,6 +246,7 @@ const run_ending = {
 	decide,
 	ended_mid_turn,
 	read_exit,
+	read_transcript,
 	written_at,
 }
 

package/scripts/run/run-invocation.ts

@@ -1,4 +1,3 @@
-import { backlog_budget_cli } from '#scripts/backlog/backlog-budget-cli'
 import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { cli_flags } from '#scripts/lib/cli-flags'
 
@@ -71,15 +70,15 @@ function tokens_of(invocation: string): ReadonlyArray<string> {
 	return invocation.split(TOKEN_SEPARATOR).filter((token) => token.length > EMPTY_LENGTH)
 }
 
-// **The integer check is `backlog:budget`'s own, imported rather than restated.** It is the command
-// this invocation is going to be handed to, so a second copy of the rule here would be free to drift
-// from the one that actually reads the number. `--only` carries no value and renders to its own
+// **The integer check is `cli_flags.to_count`, the one `backlog:budget` reads the number with.** It is
+// the command this invocation is going to be handed to, so a second copy of the rule here would be free
+// to drift from the one that actually reads the number. `--only` carries no value and renders to its own
 // constant for the same taint reason every other token does — the constant severs the record's string
 // from the rebuilt one.
 function render_option(token: ArgumentToken): string | undefined {
 	if (token.name === cli_flags.option_name(ONLY_FLAG)) return ONLY_FLAG
 	const flag = KNOWN_FLAGS.find((known) => cli_flags.option_name(known) === token.name)
-	const value = backlog_budget_cli.to_count(token.value)
+	const value = cli_flags.to_count(token.value)
 
 	if (flag === undefined || value === undefined) return undefined
 
@@ -109,7 +108,7 @@ function rendered_options(tokens: ReadonlyArray<ArgumentToken>): ReadonlyArray<s
 // `backlog:budget`'s.** It already refuses `0` and a leading zero, which is what keeps `#05` from
 // rebuilding as `#5` and being refused downstream as a rewritten record.
 // **The magnitude bound is here and not in the pattern**, which is anchored on digits and says nothing
-// about size — the same shape `backlog_budget_cli.to_count` ends with for a flag value. Without it a
+// about size — the same shape `cli_flags.to_count` ends with for a flag value. Without it a
 // number past `Number.MAX_SAFE_INTEGER` rebuilds as a different number through precision loss, and the
 // record would carry a `done` entry that never matches anything in `remaining`.
 function issue_of(token: string): number | undefined {

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

@@ -4,9 +4,8 @@ import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { lane_await } from '#scripts/lane/lane-await'
 import { cli_flags } from '#scripts/lib/cli-flags'
 import { error_text } from '#scripts/lib/error-message'
+import { MS_PER_MINUTE, MS_PER_SECOND } from '#scripts/lib/timeouts'
 import {
-	MS_PER_MINUTE,
-	MS_PER_SECOND,
 	PROCESS_ALIVE,
 	PROCESS_NONE,
 	PROCESS_UNKNOWN,
@@ -29,10 +28,6 @@ const FAILURE_EXIT_CODE = 1
 const ARGV_OFFSET = 2
 const USAGE =
 	'Usage: josh run:liveness <issue-number> --output <path> [--process alive|none] [--window <minutes>] [--gap <seconds>] [--repo <owner/repo>]'
-// Whole and positive, both of them. A zero window would call any unit not writing at that instant
-// frozen, and a zero gap would take both samples back-to-back — together they book a live unit as
-// stopped, which is the one error direction this command is built to avoid.
-const DURATION_PATTERN = /^[1-9]\d*$/u
 
 const PROCESS_TRACES: ReadonlyArray<ProcessTrace> = [PROCESS_ALIVE, PROCESS_NONE, PROCESS_UNKNOWN]
 
@@ -69,9 +64,12 @@ function to_ms(raw: string | undefined, unit_ms: number): number | undefined {
 }
 
 // A malformed duration is refused rather than silently replaced by the default: a caller that meant
-// to widen the window and mistyped it would otherwise be answered against the 30-minute one.
+// to widen the window and mistyped it would otherwise be answered against the 30-minute one. Whole and
+// positive, both of them: a zero window would call any unit not writing at that instant frozen, and a
+// zero gap would take both samples back-to-back — together they book a live unit as stopped, which is
+// the one error direction this command is built to avoid.
 function is_valid_duration(raw: string | undefined): boolean {
-	return raw === undefined || DURATION_PATTERN.test(raw)
+	return raw === undefined || cli_flags.to_positive(raw) !== undefined
 }
 
 const OPTIONS = {

package/scripts/run/run-liveness.ts

@@ -4,10 +4,12 @@ import path from 'node:path'
 import { setTimeout as sleep } from 'node:timers/promises'
 import { agent_event, type AgentEventState } from '#scripts/agent/agent-event'
 import { git_gh_issue_read } from '#scripts/gh/git-gh-issue-read'
-import { ALREADY_DONE_LABEL, NEEDS_DECISION_LABEL } from '#scripts/issue/issue-labels'
+import { has_parked_label } from '#scripts/issue/issue-labels'
 import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { issue_state } from '#scripts/issue/issue-state'
 import { PLATFORM_TEMP_ROOT } from '#scripts/josh/platform-temporary'
+import { lane_state, type LaneState } from '#scripts/lane/lane-state'
+import { MS_PER_MINUTE, MS_PER_SECOND } from '#scripts/lib/timeouts'
 import { run_hold } from '#scripts/run/hold/run-hold'
 
 // `josh run:liveness <N>` — whether the delegated unit running child `<N>` is still working, or
@@ -33,13 +35,22 @@ import { run_hold } from '#scripts/run/hold/run-hold'
 // dead. `statSync` follows the link, and the size is compared as well as the modification time,
 // because it is the two-sample size comparison that actually proves liveness.
 
+//
+// **The lane state record answers before any trace** (joshuafolkken/kit#4270): a lane `lane:pause`
+// suspended has a live process and frozen output, which the traces read as `alive` for as long as it
+// stays paused; the record says `paused`. An `ended` record is a lane done with its child. Whether a
+// child that parked or died is still there is not the record's — it writes nothing then — so the
+// traces still decide every other lane.
+
 const ALIVE_VERDICT = 'alive'
+const PAUSED_VERDICT = 'paused'
 const SETTLED_VERDICT = 'settled'
 const STOPPED_VERDICT = 'stopped'
 const UNDETERMINED_VERDICT = 'undetermined'
 
 type LivenessVerdict =
 	| typeof ALIVE_VERDICT
+	| typeof PAUSED_VERDICT
 	| typeof SETTLED_VERDICT
 	| typeof STOPPED_VERDICT
 	| typeof UNDETERMINED_VERDICT
@@ -58,8 +69,6 @@ const DEFAULT_SILENT_MINUTES = 30
 // Two samples, a few seconds apart. The gap is what turns "this file has an old timestamp" into
 // "this file is not being written", and five seconds is long enough for a unit mid-turn to append.
 const DEFAULT_GAP_SECONDS = 5
-const MS_PER_MINUTE = 60_000
-const MS_PER_SECOND = 1000
 const OPEN_STATE = 'OPEN'
 const STATE_FIELDS = 'state,labels'
 
@@ -73,6 +82,8 @@ interface Traces {
 	is_child_settled: boolean | undefined
 	is_output_frozen: boolean | undefined
 	is_tree_dirty: boolean
+	// The lane's state record's state; `undefined` where the lane has none.
+	lane_state?: LaneState | undefined
 	process_trace: ProcessTrace
 }
 
@@ -95,8 +106,10 @@ interface LivenessRequest {
 const REASONS: Record<LivenessVerdict, string> = {
 	[ALIVE_VERDICT]:
 		'The unit is still working: its output moved, or a process of the child is alive.',
+	[PAUSED_VERDICT]:
+		'The lane state record says the lane is paused: its child is suspended, not working, and nothing moves until someone resumes it.',
 	[SETTLED_VERDICT]:
-		'The child is closed, parked with `needs-decision`, or marked `already-done`, so there is nothing here to recover.',
+		'The child is closed, parked with `needs-decision` or `run:stalled`, or marked `already-done`, so there is nothing here to recover.',
 	[STOPPED_VERDICT]:
 		'The output has been frozen past the silent window and no process of the child is alive in that checkout.',
 	[UNDETERMINED_VERDICT]:
@@ -104,6 +117,8 @@ const REASONS: Record<LivenessVerdict, string> = {
 }
 
 const ALIVE_ADVICE = 'Keep waiting on `pnpm josh lane:await`; do not touch the child.'
+const PAUSED_ADVICE =
+	'Do not wait on it and do not recover it: tell the person the lane is paused; `pnpm josh lane:resume <N>` resumes it once they ask.'
 const SETTLED_ADVICE =
 	'Read the child with `pnpm josh issue:state <N>` and take the branch its state says.'
 // The unit stopped, but *why* it stopped — abandoned mid-implementation, or dead because it could not
@@ -112,11 +127,11 @@ const SETTLED_ADVICE =
 // routed through `run:merge --output`, the same composite a returned child takes: it reads the exit
 // record without waiting for the unit to return, re-dispatches an outage child (counting the outage,
 // and stopping the run on the environment guard once a run of them trips it), and parks an abandoned
-// child with `needs-decision` against the consecutive-failure guard.
+// child with `run:stalled` against the consecutive-failure guard.
 const STOPPED_CLEAN_ADVICE =
-	'The unit ended — classify how before booking it. Run `pnpm josh run:merge <N> --output <path>` (add `--epic <E> --repo <owner/repo> --owner "$PPID"` for a named epic): it reads the child\'s exit record without waiting for the unit to return, re-dispatches a child that could not reach the API (counting the outage; a run of them trips the environment guard and stops the run), and parks an abandoned child with `needs-decision` against the consecutive-failure guard. The checkout is clean, so there is nothing to stash.'
+	'The unit ended — classify how before booking it. Run `pnpm josh run:merge <N> --output <path>` (add `--epic <E> --repo <owner/repo> --owner "$PPID"` for a named epic): it reads the child\'s exit record without waiting for the unit to return, re-dispatches a child that could not reach the API (counting the outage; a run of them trips the environment guard and stops the run), and parks an abandoned child with `run:stalled` against the consecutive-failure guard. The checkout is clean, so there is nothing to stash.'
 const STOPPED_DIRTY_ADVICE =
-	'Stash the half-finished work with `git stash push -u -m "backlogrun: stopped unit for #<N>"` and record it on the Issue, then classify how the unit ended with `pnpm josh run:merge <N> --output <path>` (add `--epic <E> --repo <owner/repo> --owner "$PPID"` for a named epic): it re-dispatches an API-outage child (counting the outage; a run of them trips the environment guard) and parks an abandoned child with `needs-decision` against the consecutive-failure guard, without waiting for the unit to return.'
+	'Stash the half-finished work with `pnpm josh stash:push "backlogrun: stopped unit for #<N>"` and record it on the Issue, then classify how the unit ended with `pnpm josh run:merge <N> --output <path>` (add `--epic <E> --repo <owner/repo> --owner "$PPID"` for a named epic): it re-dispatches an API-outage child (counting the outage; a run of them trips the environment guard) and parks an abandoned child with `run:stalled` against the consecutive-failure guard, without waiting for the unit to return.'
 const UNDETERMINED_ADVICE =
 	'Read the trace that failed and ask again. Where the process trace was given as `unknown`, leave `--process` out so the command reads it. Two of these in a row is a fault in the check itself rather than a slow unit: stop polling and report it.'
 
@@ -134,8 +149,19 @@ function is_agent_finished(traces: Traces): boolean {
 	return is_agent_state_finished(traces.agent_state)
 }
 
+// What the lane state record answers on its own: a paused lane, or one done with its child.
+function recorded_verdict(state: LaneState | undefined): LivenessVerdict | undefined {
+	if (state === 'paused') return PAUSED_VERDICT
+
+	return state === 'ended' ? SETTLED_VERDICT : undefined
+}
+
 function definitive_verdict(traces: Traces): LivenessVerdict | undefined {
 	if (traces.is_child_settled === true) return SETTLED_VERDICT
+
+	const recorded = recorded_verdict(traces.lane_state)
+
+	if (recorded !== undefined) return recorded
 	if (is_agent_finished(traces)) return STOPPED_VERDICT
 	if (is_output_moving(traces)) return ALIVE_VERDICT
 
@@ -171,10 +197,16 @@ function to_verdict(traces: Traces): LivenessVerdict {
 	return is_check_running(traces) ? ALIVE_VERDICT : STOPPED_VERDICT
 }
 
+// The advice for every verdict but `stopped`, whose advice turns on the work left to stash.
+const ADVICE: Record<Exclude<LivenessVerdict, typeof STOPPED_VERDICT>, string> = {
+	[ALIVE_VERDICT]: ALIVE_ADVICE,
+	[PAUSED_VERDICT]: PAUSED_ADVICE,
+	[SETTLED_VERDICT]: SETTLED_ADVICE,
+	[UNDETERMINED_VERDICT]: UNDETERMINED_ADVICE,
+}
+
 function to_advice(verdict: LivenessVerdict, has_work_to_stash: boolean): string {
-	if (verdict === ALIVE_VERDICT) return ALIVE_ADVICE
-	if (verdict === SETTLED_VERDICT) return SETTLED_ADVICE
-	if (verdict === UNDETERMINED_VERDICT) return UNDETERMINED_ADVICE
+	if (verdict !== STOPPED_VERDICT) return ADVICE[verdict]
 
 	return has_work_to_stash ? STOPPED_DIRTY_ADVICE : STOPPED_CLEAN_ADVICE
 }
@@ -307,19 +339,13 @@ async function read_output_frozen(request: FreshnessRequest): Promise<boolean |
 	return second.mtime_ms === first.mtime_ms && second.size === first.size
 }
 
-function carries_label(labels: ReadonlyArray<string>, wanted: string): boolean {
-	return labels.some((label) => label.toLowerCase() === wanted)
-}
-
-// The labels that say a unit stopped on purpose. `needs-decision` is the park branch; `already-done`
-// is the exit a child takes when it verifies its Issue's work is already merged
-// — it comments the evidence, applies the label and stops with the checkout
+// The park labels (`PARKED_LABELS`) say a unit stopped on purpose. `needs-decision` and `run:stalled`
+// are the park branches; `already-done` is the exit a child takes when it verifies its Issue's work is
+// already merged — it comments the evidence, applies the label and stops with the checkout
 // clean, which is settled by the same reasoning. Left out, this command reports a child that
 // finished correctly as `stopped` and a supervisor restarts the investigation it just completed.
-const SETTLED_LABELS: ReadonlyArray<string> = [NEEDS_DECISION_LABEL, ALREADY_DONE_LABEL]
-
 function carries_settled_label(labels: ReadonlyArray<string>): boolean {
-	return SETTLED_LABELS.some((label) => carries_label(labels, label))
+	return has_parked_label(labels)
 }
 
 // Settled needs positive evidence that the child is done with: it closed, or the unit parked it and
@@ -340,20 +366,25 @@ async function read_child_settled(issue: string, repo?: string): Promise<boolean
 	return state.state !== OPEN_STATE || carries_settled_label(state.labels)
 }
 
+function freshness_of(request: LivenessRequest): FreshnessRequest {
+	return {
+		gap_ms: request.gap_ms ?? DEFAULT_GAP_SECONDS * MS_PER_SECOND,
+		now_ms: Date.now(),
+		output_path: request.output_path,
+		silent_window_ms: request.silent_window_ms ?? DEFAULT_SILENT_MINUTES * MS_PER_MINUTE,
+	}
+}
+
 // The dirty tree is deliberately not one of the traces, so it is the one input that does not answer
 // `undetermined`. `run_hold.is_tree_dirty` reports an unreadable checkout as dirty, which here means
 // the advice offers a stash that may find nothing — the safe direction for the only question this
 // input decides, and one that cannot move the verdict.
 async function read_traces(request: LivenessRequest): Promise<Traces> {
-	const [is_initial_child_settled, is_output_frozen, is_tree_dirty] = await Promise.all([
+	const [is_initial_child_settled, is_output_frozen, is_tree_dirty, record] = await Promise.all([
 		read_child_settled(request.issue, request.repo),
-		read_output_frozen({
-			gap_ms: request.gap_ms ?? DEFAULT_GAP_SECONDS * MS_PER_SECOND,
-			now_ms: Date.now(),
-			output_path: request.output_path,
-			silent_window_ms: request.silent_window_ms ?? DEFAULT_SILENT_MINUTES * MS_PER_MINUTE,
-		}),
+		read_output_frozen(freshness_of(request)),
 		run_hold.is_tree_dirty(),
+		lane_state.read_state(request.issue),
 	])
 	const agent_state = read_agent_state(request.output_path)
 	// A child can close or park its Issue and append its terminal event after the parallel GitHub read
@@ -370,6 +401,7 @@ async function read_traces(request: LivenessRequest): Promise<Traces> {
 		is_child_settled,
 		is_output_frozen,
 		is_tree_dirty,
+		lane_state: record?.state,
 		process_trace: request.process_trace,
 	}
 }
@@ -400,8 +432,7 @@ export {
 	ALIVE_VERDICT,
 	DEFAULT_GAP_SECONDS,
 	DEFAULT_SILENT_MINUTES,
-	MS_PER_MINUTE,
-	MS_PER_SECOND,
+	PAUSED_VERDICT,
 	PROCESS_ALIVE,
 	PROCESS_NONE,
 	PROCESS_UNKNOWN,

package/scripts/run/run-next.ts

@@ -14,7 +14,7 @@ import { run_step, type PreVerdict } from './run-step'
 const ALREADY_DONE_STEP =
 	'Issue is CLOSED — nothing to run. Verify it against merged code before starting.'
 const KEEP_WORK_STEP =
-	'Issue is CLOSED but this lane holds uncommitted work — stash it with `git stash push -u -m "<N>: uncommitted work at already-done"` before ending.'
+	'Issue is CLOSED but this lane holds uncommitted work — stash it with `pnpm josh stash:push "<N>: uncommitted work at already-done"` before ending.'
 const LATEST_STEP =
 	'Update dependencies first (latest: required), load the dependency-update skill, then implement.'
 const HUMAN_REVIEW_STEP =

package/scripts/run/run-parent-cut-hook.ts

@@ -1,9 +1,9 @@
 import { CONTEXT_CUT_THRESHOLD } from '#scripts/cost-runtime/context-cut-threshold'
 import { cost_cli, type CostVerdict } from '#scripts/cost-runtime/cost-cli'
-import { cost_format } from '#scripts/cost-runtime/cost-format'
 import { cost_verdict } from '#scripts/cost-runtime/cost-verdict'
 import { hook_decision } from '#scripts/josh/hook-decision'
 import { error_text } from '#scripts/lib/error-message'
+import { figure_format } from '#scripts/lib/figure-format'
 import { implementation_cut_verdict } from '#scripts/rules/implementation-cut-verdict'
 import type { RunCarry } from '#scripts/run/carry/run-carry'
 import { run_headless } from './run-headless'
@@ -50,7 +50,7 @@ function current_state(): ParentCutState {
 	}
 }
 
-const THRESHOLD_TEXT = `${cost_format.format_tokens(CONTEXT_CUT_THRESHOLD)}-token`
+const THRESHOLD_TEXT = `${figure_format.format_tokens(CONTEXT_CUT_THRESHOLD)}-token`
 
 const PARENT_CUT_REASON =
 	'⛔ backlogrun parent hand-off: this session drives a `backlogrun` and its recent-context cost ' +

package/scripts/run/run-preflight.ts

@@ -1,8 +1,10 @@
 import { git_gh_pr_read } from '#scripts/gh/git-gh-pr-read'
 import { git_command } from '#scripts/git/git-command'
+import { git_stash } from '#scripts/git/stash/git-stash'
 import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { session_cite } from '#scripts/issue/session-cite'
 import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
+import { error_text } from '#scripts/lib/error-message'
 import { json_value } from '#scripts/lib/json-value'
 import { run_hold } from '#scripts/run/hold/run-hold'
 import { z } from 'zod'
@@ -162,13 +164,13 @@ function to_reason(verdict: PreflightVerdict, tree: TreeState, child: ChildState
 // comment is the only thing that can ever bring it back.
 //
 // **The stash lines appear only over a dirty tree.** `reclaim` also answers a clean checkout parked on
-// a feature branch, and printing them there tells the caller to record a stash `git stash push` never
+// a feature branch, and printing them there tells the caller to record a stash `stash:push` never
 // created — an Issue comment naming nothing, under a rule that says the comment is what restores it.
 function reclaim_steps(tree: TreeState, issue: string): Array<string> {
 	if (!tree.is_dirty) return []
 
 	return [
-		`git stash push -u -m "${STASH_LABEL_PREFIX}${issue}"`,
+		`pnpm josh stash:push "${STASH_LABEL_PREFIX}${issue}"`,
 		`Record the stash on ${session_cite.issue(issue)} — the comment is what gets it popped; nothing pops it for you.`,
 	]
 }
@@ -211,9 +213,22 @@ function to_pr_state(raw: string): PrState {
 	return (state === undefined ? undefined : GH_PR_STATES.get(state)) ?? NO_PR
 }
 
+// Dirty means work `stash:push` would set aside: a tree whose only change is the observation ledger
+// would otherwise be told to stash, get `clean`, and be told to stash again. Unreadable is dirty, as
+// in `run_hold.is_tree_dirty`.
+async function has_stashable_work(): Promise<boolean> {
+	try {
+		return await git_stash.has_stashable_changes()
+	} catch (error) {
+		error_text.trace_swallowed('run_preflight.has_stashable_work', error)
+
+		return true
+	}
+}
+
 async function read_tree_state(): Promise<TreeState> {
 	const [is_dirty, current, default_branch] = await Promise.all([
-		run_hold.is_tree_dirty(),
+		has_stashable_work(),
 		git_command.branch(),
 		git_command.get_default_branch(),
 	])

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

@@ -1,5 +1,3 @@
-#!/usr/bin/env tsx
-import { fileURLToPath } from 'node:url'
 import { git_stash } from '#scripts/git/stash/git-stash'
 import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { issue_read_cli, type BlockRead } from '#scripts/issue/issue-read-cli'
@@ -26,7 +24,6 @@ import { run_prep_locate } from './run-prep-locate'
 
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
-const ARGV_OFFSET = 2
 const USAGE = 'Usage: josh run:prep <issue-number>'
 const LANE_SKIP_SCOPE = 'not asked'
 const LANE_SKIP_REASON =
@@ -88,7 +85,7 @@ async function lane_has_changes(): Promise<boolean> {
 	if (!lane_child_marker.is_child_of(process.cwd())) return false
 
 	try {
-		return await git_stash.has_changes(process.cwd())
+		return await git_stash.has_stashable_changes(process.cwd())
 	} catch (error) {
 		error_text.trace_swallowed('run_prep_cli.lane_has_changes', error)
 
@@ -155,14 +152,8 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 	return exit_code(reads)
 }
 
-async function main(argv: ReadonlyArray<string>): Promise<void> {
-	process.exitCode = await run(argv)
-}
-
 // `gather` and `to_parts` are exported so `run:next` reads the same state from the same three reads
 // rather than growing a second copy of the gather.
 const run_prep_cli = { gather, parse_number, run, to_parts }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
-
 export { run_prep_cli }

package/scripts/run/run-prep-locate.ts

@@ -1,4 +1,4 @@
-import { get_exit_code } from '#scripts/git/git-execa-error'
+import { git_grep_hits, type Hit } from '#scripts/git/git-grep-hits'
 import { git_spawn } from '#scripts/git/git-spawn'
 
 // The code locations an issue names, bundled into `run:prep`. Investigation is most of a run's
@@ -17,18 +17,13 @@ const LINE_SUFFIX = /(?::\d+)+$/u
 // A name carries a separator a prose word does not — `run:prep`, `run_prep`, `run-prep.ts`, `a/b`.
 const NAME_CHARACTERS = /^[\w@./:-]+$/u
 const NAME_SEPARATOR = /[./:_-]/u
-const GREP_LINE = /^(?<path>[^:]+):(?<line>\d+):(?<text>.*)$/u
 const MIN_TARGET_LENGTH = 3
 const MAX_TARGETS = 10
 const MAX_FILES_PER_TARGET = 3
-const MAX_EXCERPT_LENGTH = 80
-const ELLIPSIS = '…'
 const INDENT = '  '
 const HIT_SEPARATOR = '  '
 const NO_MATCH = ' — no match in code'
 const SEARCH_FAILED = ' — git grep failed; not searched'
-// `git grep` exits 1 for no match; any other exit is a search that never ran.
-const GREP_NO_MATCH_EXIT = 1
 const FILE_PATHSPEC = ':(glob)**/'
 const FILE_HIT = { line: '1', excerpt: '(file named in the issue)' }
 const NO_TARGETS = '(no backticked path or identifier in the issue)'
@@ -43,12 +38,6 @@ const CODE_PATHS = [
 	':(exclude)*.snap',
 ]
 
-interface Hit {
-	path: string
-	line: string
-	excerpt: string
-}
-
 interface Located {
 	target: string
 	hits: ReadonlyArray<Hit>
@@ -73,32 +62,6 @@ function extract_targets(text: string): Array<string> {
 	return [...new Set(targets.filter((target) => is_name(target)))].slice(0, MAX_TARGETS)
 }
 
-function shorten(text: string): string {
-	const trimmed = text.trim()
-
-	if (trimmed.length <= MAX_EXCERPT_LENGTH) return trimmed
-
-	return `${trimmed.slice(0, MAX_EXCERPT_LENGTH)}${ELLIPSIS}`
-}
-
-// `git grep -n` prints `path:line:text`; the text may itself hold colons, so only the first two split.
-function to_hit(output_line: string): Hit | undefined {
-	const groups = GREP_LINE.exec(output_line)?.groups
-
-	if (groups === undefined) return undefined
-
-	// All three groups are non-optional in `GREP_LINE`, so a match always carries each of them.
-	const { path, line, text } = groups as Record<'line' | 'path' | 'text', string>
-
-	return { path, line, excerpt: shorten(text) }
-}
-
-function parse_hits(stdout: string): Array<Hit> {
-	const hits = stdout.split('\n').map((line) => to_hit(line))
-
-	return hits.filter((hit): hit is Hit => hit !== undefined).slice(0, MAX_FILES_PER_TARGET)
-}
-
 function format_target(located: Located): string {
 	if (located.has_failed) return `${located.target}${SEARCH_FAILED}`
 	if (located.hits.length === 0) return `${located.target}${NO_MATCH}`
@@ -116,18 +79,12 @@ function format_locations(located: ReadonlyArray<Located>): string {
 	return located.map((entry) => format_target(entry)).join('\n')
 }
 
-// `git grep` exits 1 when nothing matches, which `git_spawn.read` raises. Neither that nor a search
-// that could not run fails the bundle — the issue body is still worth printing without it — but only
-// the first is reported as "no match": a git without `grep -m` (older than 2.38) exits 129, and naming
-// every target absent then would send the reader away from code that is there.
+// Neither a no-match nor a search that could not run fails the bundle — the issue body is still worth
+// printing without it — but only the first is reported as "no match" (`git-grep-hits.ts`).
 async function grep(target: string): Promise<Located> {
-	const grep_arguments = ['grep', '-n', '-I', '-F', '-m', '1', '-e', target, '--', ...CODE_PATHS]
+	const { hits, has_failed } = await git_grep_hits.search(target, ['-m', '1'], CODE_PATHS)
 
-	try {
-		return { target, hits: parse_hits(await git_spawn.read(grep_arguments)), has_failed: false }
-	} catch (error) {
-		return { target, hits: [], has_failed: get_exit_code(error) !== GREP_NO_MATCH_EXIT }
-	}
+	return { target, hits: hits.slice(0, MAX_FILES_PER_TARGET), has_failed }
 }
 
 // A path is rarely spelled out inside code — imports drop the extension and resolve relatively — so
@@ -158,7 +115,7 @@ async function locate(text: string): Promise<string> {
 	return format_locations(located)
 }
 
-const run_prep_locate = { extract_targets, locate, parse_hits }
+const run_prep_locate = { extract_targets, locate }
 
-export type { Hit, Located }
+export type { Located }
 export { run_prep_locate }

package/scripts/run/run-prep-main.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { run_prep_cli } from './run-prep-cli'
+
+// The `josh run:prep` entry, kept apart from `run-prep-cli.ts` because other modules import that
+// one: a bundle is one file, so a main guard there would fire for every command that carries it
+// (joshuafolkken/kit#4186).
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const ARGV_OFFSET = 2
+
+	process.exitCode = await run_prep_cli.run(process.argv.slice(ARGV_OFFSET))
+}