@joshuafolkken/kit 1.1514.0 → 1.2114.0

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

@@ -1,7 +1,7 @@
 // The pure decisions `josh run:review` makes, kept apart from the side effects the same way
 // `run-merge.ts` is kept apart from `run-merge-steps.ts`.
 //
-// `run:review` starts the gate in the background and prints the `/code-review` brief in one call, so a
+// `run:review` starts the gate in the background and writes the `/code-review` brief in one call, so a
 // lane child launches both from a single command and the two overlap rather than running one after the
 // other. Two facts have to be decided from what the stamps say, and both are decided here so a test can
 // pin them without a gate ever running:
@@ -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'
 
@@ -27,26 +29,41 @@ function adopt_verdict(is_gate_green: boolean): AdoptVerdict {
 const GATE_GREEN = 'green'
 const GATE_RUNNING = 'running'
 const GATE_RED = 'red'
+const GATE_MOVED = 'moved'
 
-type GateState = typeof GATE_GREEN | typeof GATE_RUNNING | typeof GATE_RED
+type GateState = typeof GATE_GREEN | typeof GATE_RUNNING | typeof GATE_RED | typeof GATE_MOVED
 
-// The three states the join waits on, decided from two readings the steps take of the stamps a real
-// `josh gate` writes: a green stamp covering this tree, and the in-flight marker's writer still alive.
+// The four states the join waits on, decided from three readings the steps take of the stamps a real
+// `josh gate` writes: a green stamp covering this tree, the in-flight marker's writer still alive, and
+// a green stamp covering the tree this pair's gate started on.
 // Green wins over running, because a gate that has already recorded green is done however the marker
 // reads; a marker whose writer is gone with no green stamp is a gate that finished red or died, which
 // is the safe direction — the join reports red and the verdict is blocked.
-function gate_state(is_green: boolean, is_running: boolean): GateState {
+//
+// **A gate that finished green on a tree that has since moved is not red** (joshuafolkken/kit#4774): a
+// round-1 reviewer fixing in place moves the tree after the gate recorded green, so the stamp no longer
+// covers it. That is `moved` — still not adoptable, but the gate never failed, and the gate that
+// follows re-runs on the moved tree.
+function gate_state(is_green: boolean, is_running: boolean, is_moved = false): GateState {
 	if (is_green) return GATE_GREEN
 	if (is_running) return GATE_RUNNING
+	if (is_moved) return GATE_MOVED
 
 	return GATE_RED
 }
 
+// The `--join` exit code of a `moved` gate, read by `josh ship` (`run-ship-review-steps.ts`).
+const MOVED_EXIT_CODE = 2
+// The `--join` exit code of an unpinned change the background `test:pinned` found
+// (joshuafolkken/kit#4770). `josh ship` never drains it, whatever the reviewer fixed.
+const UNPINNED_EXIT_CODE = 3
+// `josh ship` opens the interaction brief itself, so its `run:review` opens code's alone.
+const CODE_ONLY_FLAG = '--code-only'
+
 function is_gate_settled(state: GateState): boolean {
 	return state !== GATE_RUNNING
 }
 
-const MS_PER_SECOND = 1000
 const SECONDS_DECIMALS = 1
 const NO_OVERLAP = 0
 
@@ -99,9 +116,13 @@ function format_timing(timing: ReviewTiming): string {
 const run_review = {
 	ADOPT,
 	BLOCKED,
+	CODE_ONLY_FLAG,
 	GATE_GREEN,
+	GATE_MOVED,
 	GATE_RED,
 	GATE_RUNNING,
+	MOVED_EXIT_CODE,
+	UNPINNED_EXIT_CODE,
 	adopt_verdict,
 	format_timing,
 	gate_state,
@@ -114,4 +135,4 @@ export type { AdoptVerdict, GateState, ReviewTiming, TimingStart }
 // object their literal types widen to `string`, so a test passing `run_review.GATE_RED` to a
 // `GateState` parameter would not type-check — the same reason `run-liveness.ts` exports its verdicts
 // by name.
-export { GATE_GREEN, GATE_RED, GATE_RUNNING, run_review }
+export { GATE_GREEN, GATE_MOVED, GATE_RED, GATE_RUNNING, run_review }

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,6 +1,4 @@
-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'
@@ -50,10 +48,11 @@ function current_state(): ParentCutState {
 	}
 }
 
-const THRESHOLD_TEXT = `${cost_format.format_tokens(CONTEXT_CUT_THRESHOLD)}-token`
+// Named by its command, never spelled: the threshold is priced at the session's own model.
+const THRESHOLD_TEXT = '`pnpm josh cost --cut`'
 
 const PARENT_CUT_REASON =
-	'⛔ backlogrun parent hand-off: this session drives a `backlogrun` and its recent-context cost ' +
+	'⛔ backlogrun parent hand-off: this session drives a `backlogrun` and its recent context ' +
 	`crossed the ${THRESHOLD_TEXT} threshold between merges. Take the hand-off now: open no new lane, ` +
 	'follow `backlogrun-progress.md` → "The hand-off" (`pnpm josh run:carry --cut --owner "$PPID"`, then ' +
 	'`pnpm josh run:wake` unless `capped`) and end the turn. Reissue this call once done or if it ' +

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

package/scripts/run/run-prep.ts

@@ -1,3 +1,4 @@
+import { delegation_policy } from '#scripts/delegation/delegation-policy'
 import { issue_state, type IssueState } from '#scripts/issue/issue-state'
 
 // `josh run:prep <N>` — the reads a `fullrun` makes before its first edit, assembled into one report.
@@ -22,6 +23,9 @@ const CONTENT_HEADER = '=== issue ==='
 const STATE_HEADER = '=== state ==='
 const LATEST_HEADER = '=== dependency update ==='
 const LOCATIONS_HEADER = '=== code locations ==='
+const INVESTIGATION_HEADER = '=== investigation ==='
+// The step the investigation guard would otherwise name only once it refuses, mid-reading (#4345).
+const INVESTIGATION_BODY = `Delegate before the first read — the guard refuses at ${delegation_policy.INVESTIGATION_LIMIT}. ${delegation_policy.INVESTIGATION_STEP} Brief it with the code locations above; read in the main line only the files this run will edit.`
 const SHIP_HEADER = '=== ship preconditions ==='
 const SHIP_MET = 'met — nothing `josh ship` refuses on as the tree stands'
 const SHIP_UNMET =
@@ -89,12 +93,14 @@ function format_report(parts: PrepParts): string {
 		section(STATE_HEADER, state_body(parts)),
 		section(LATEST_HEADER, `${parts.latest_scope}${LATEST_JOINER}${parts.latest_reason}`),
 		section(LOCATIONS_HEADER, parts.locations),
+		section(INVESTIGATION_HEADER, INVESTIGATION_BODY),
 		section(SHIP_HEADER, ship_body(parts.ship_problems)),
 	].join(SECTION_SEPARATOR)
 }
 
 const run_prep = {
 	CONTENT_HEADER,
+	INVESTIGATION_HEADER,
 	LATEST_HEADER,
 	LOCATIONS_HEADER,
 	SHIP_HEADER,
@@ -103,6 +109,7 @@ const run_prep = {
 	SUMMARY_PREFIX,
 	format_report,
 	ship_body,
+	summary,
 }
 
 export type { PrepParts }