@joshuafolkken/kit 1.1471.0 → 1.1784.0

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,15 +106,19 @@ 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]:
 		'A trace could not be read, so this says nothing about the unit. A trace that could not be read answers `undetermined`, never `stopped`.',
 }
 
-const ALIVE_ADVICE = 'Keep polling; do not touch the child.'
+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-poll-hook.ts

@@ -0,0 +1,157 @@
+import { hook_decision } from '#scripts/josh/hook-decision'
+import { error_text } from '#scripts/lib/error-message'
+import { time_density_hook } from '#scripts/time-runtime/time-density-hook'
+import { time_shell } from '#scripts/time-runtime/time-shell'
+import { time_spans, type Span } from '#scripts/time-runtime/time-spans'
+import { run_headless } from './run-headless'
+import { run_watcher_hook } from './run-watcher-hook'
+
+// The `backlogrun` parent's and the wake session's poll, refused at its first repeat.
+//
+// **The parent waits on a blocking command, never on a re-read.** `backlog:drive` and `lane:await` hold
+// the turn until something the model has to read happens; a state read issued again with nothing
+// decided in between is a poll, and each one is a model turn spent on an answer that has not changed.
+//
+// **"Nothing decided in between" is read off the transcript**: the last completed call before this one
+// ran the same state read on the same operands, with no person's prompt after it. A different command, a person's prompt or
+// any other tool call in between breaks the streak, so a progress question answered twice is not one.
+//
+// **The parent test is `run_headless.driving_carry`'s**, the one the parent hand-off guard reads, so a
+// lane child, a person's session and a handed-off record are left alone. A wake session adopts the
+// record, so it reads as the parent here.
+
+const SWITCH_ENV_KEY = 'JOSH_POLL_GUARD'
+const BASH_TOOL = 'Bash'
+const STATE_READS: ReadonlySet<string> = new Set([
+	'josh lane:list',
+	'josh lane:output',
+	'josh run:board',
+	'josh run:carry',
+	'josh run:liveness',
+	'josh run:progress',
+	'josh run:wake',
+])
+
+const POLL_REASON =
+	'⛔ poll: this `backlogrun` session repeats a state read with nothing decided in between, on every ' +
+	'occurrence. Wait on `pnpm josh backlog:drive`, or `pnpm josh lane:await <N...> --owner "$PPID"` in ' +
+	'the background, and end the turn; its exit is the wake.'
+
+// The flags that make a state-read command write: `run:carry --filed` twice is two filings, and
+// `run:carry --cut` after `run:carry --json` is the hand-off, so neither is a re-read.
+const WRITING_FLAGS: ReadonlySet<string> = new Set([
+	'--begin',
+	'--cut',
+	'--done',
+	'--end',
+	'--every',
+	'--filed',
+	'--loop',
+	'--mark',
+	'--merged',
+	'--resume',
+	'--retrospective',
+	'--start',
+	'--stop',
+	'--wait',
+])
+
+const FLAG_PREFIX = '-'
+const NAME_WORDS = 2
+const SIGNATURE_SEPARATOR = ' '
+
+// A state read keyed by the command and its operands, or `undefined` for a call that is none.
+// **Operands, not flags**: `lane:output 1 <path>` then `lane:output 2 <path>` read two children, while
+// `run:board` and `run:board --chat` print one answer.
+function read_key(signature: string): string | undefined {
+	const words = signature.split(SIGNATURE_SEPARATOR)
+	const name = words.slice(0, NAME_WORDS).join(SIGNATURE_SEPARATOR)
+
+	if (!STATE_READS.has(name) || words.some((word) => WRITING_FLAGS.has(word))) return undefined
+
+	return words.filter((word) => !word.startsWith(FLAG_PREFIX)).join(SIGNATURE_SEPARATOR)
+}
+
+function read_keys(signatures: ReadonlyArray<string>): Array<string> {
+	return signatures.map((signature) => read_key(signature)).filter((key) => key !== undefined)
+}
+
+function state_reads_of(command: string): ReadonlyArray<string> {
+	return read_keys(time_shell.josh_signatures_of(command))
+}
+
+function command_of(input: unknown): string {
+	if (typeof input !== 'object' || input === null || !('command' in input)) return ''
+
+	return typeof input.command === 'string' ? input.command : ''
+}
+
+// The state reads the call runs, or none for a call this guard never judges: not a shell call, or a
+// delegated unit's (it names the parent's transcript, so only `agent_id` tells it apart).
+function candidate_reads(raw_payload: string): ReadonlyArray<string> {
+	const payload = hook_decision.parse_hook_payload(raw_payload)
+
+	if (payload?.tool_name !== BASH_TOOL || (payload.agent_id ?? '') !== '') return []
+
+	return state_reads_of(command_of(payload.tool_input))
+}
+
+// The last completed call or person's prompt; a model span is the turn itself, never a decision.
+function last_step(tail: string): Span | undefined {
+	return time_spans
+		.parse_timeline(tail)
+		.spans.findLast((span) => span.category !== time_spans.MODEL_CATEGORY)
+}
+
+function repeats_last_call(tail: string, reads: ReadonlyArray<string>): boolean {
+	const last = last_step(tail)
+
+	if (last?.category !== time_spans.TOOL_CATEGORY) return false
+
+	const last_reads = read_keys(last.josh_signatures)
+
+	return reads.some((key) => last_reads.includes(key))
+}
+
+// Every cheap test first: the carry record is read only for a call that already repeats a state read.
+function is_repeat(raw_payload: string): boolean {
+	const reads = hook_decision.is_switch_enabled(SWITCH_ENV_KEY) ? candidate_reads(raw_payload) : []
+	const transcript = reads.length === 0 ? undefined : run_watcher_hook.transcript_of(raw_payload)
+
+	if (transcript === undefined) return false
+
+	return repeats_last_call(time_density_hook.read_tail(transcript), reads)
+}
+
+/**
+ * The deny reason for a state read the driving `backlogrun` parent (or its wake session) issues again
+ * with nothing decided since the last one, or `undefined` when the call proceeds.
+ */
+async function poll_reason(
+	raw_payload: string,
+	is_parent: () => Promise<boolean> = run_headless.is_backlog_parent,
+): Promise<string | undefined> {
+	if (!is_repeat(raw_payload)) return undefined
+
+	return (await is_parent()) ? POLL_REASON : undefined
+}
+
+// It fails open: an unreadable transcript or carry record allows the call rather than wedging the run.
+async function safe_poll_reason(raw_payload: string): Promise<string | undefined> {
+	try {
+		return await poll_reason(raw_payload)
+	} catch (error) {
+		error_text.trace_swallowed('run_poll_hook.poll_reason', error)
+
+		return undefined
+	}
+}
+
+const run_poll_hook = {
+	POLL_REASON,
+	SWITCH_ENV_KEY,
+	poll_reason,
+	safe_poll_reason,
+}
+
+export { run_poll_hook }

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,