@joshuafolkken/kit 1.957.0 → 1.972.0

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

@@ -43,8 +43,14 @@ const RELEASE_FLAG = '--release'
 // cannot — clearing a record somebody else left behind — is spelled out rather than reached by
 // typing the ordinary command.
 const FORCE_FLAG = '--force'
+// What `fullrun #N`'s entry claims with, so the record says the run is a `fullrun` — the one run whose
+// implementation cut outside a lane resumes as `fullrun #N` (joshuafolkken/kit#2760).
+const FULLRUN_FLAG = '--fullrun'
+// The most a claim reads: the issue number and the `--fullrun` flag after it.
+const MAX_CLAIM_ARGUMENTS = 2
 const ISSUE_NUMBER_PATTERN = /^[1-9]\d*$/u
-const USAGE = 'Usage: josh run:hold [<issue-number>] | josh run:release [<issue-number> | --force]'
+const USAGE =
+	'Usage: josh run:hold [<issue-number> [--fullrun]] | josh run:release [<issue-number> | --force]'
 
 const HOLD_VERDICT = 'hold'
 const BUSY_VERDICT = 'busy'
@@ -57,10 +63,14 @@ const HELD_VERDICT = 'held'
 
 const FORCE_RELEASE_KIND = 'force-release'
 
+interface ClaimRequest {
+	kind: 'claim'
+	issue: string
+	is_fullrun?: boolean
+}
+
 type HoldRequest =
-	| { kind: 'release'; claimant: string }
-	| { kind: typeof FORCE_RELEASE_KIND }
-	| { kind: 'claim'; issue: string }
+	ClaimRequest | { kind: 'release'; claimant: string } | { kind: typeof FORCE_RELEASE_KIND }
 
 const FORCE_RELEASE_REQUEST: HoldRequest = { kind: FORCE_RELEASE_KIND }
 
@@ -68,14 +78,21 @@ function release_request(claimant: string): HoldRequest {
 	return { kind: 'release', claimant }
 }
 
+// The flag after a numbered claim: absent, or `--fullrun`. Anything else is a usage error.
+function numbered_claim(issue: string, flag: string | undefined): HoldRequest | undefined {
+	if (flag === undefined) return { kind: 'claim', issue }
+
+	return flag === FULLRUN_FLAG ? { kind: 'claim', issue, is_fullrun: true } : undefined
+}
+
 function parse_claim(argv: ReadonlyArray<string>): HoldRequest | undefined {
-	const [first] = argv
+	const [first, flag] = argv
 
 	if (first === undefined) return { kind: 'claim', issue: run_hold.UNNUMBERED_ISSUE }
 
-	if (argv.length > 1 || !ISSUE_NUMBER_PATTERN.test(first)) return undefined
+	if (argv.length > MAX_CLAIM_ARGUMENTS || !ISSUE_NUMBER_PATTERN.test(first)) return undefined
 
-	return { kind: 'claim', issue: first }
+	return numbered_claim(first, flag)
 }
 
 function parse_release_argument(first: string): HoldRequest | undefined {
@@ -135,8 +152,10 @@ async function blocking_message(read: HoldRead): Promise<string | undefined> {
 
 // A record already here is never overwritten by a claim: overwriting is what the guard exists to
 // prevent, and the person who knows the other run has ended clears it with `run:release --force`.
-function take_free_tree(target: string, issue: string): number {
-	if (run_hold.create_hold(target, issue)) return report_hold()
+function take_free_tree(target: string, request: ClaimRequest): number {
+	const is_taken = run_hold.create_hold(target, request.issue, new Date(), request.is_fullrun)
+
+	if (is_taken) return report_hold()
 
 	return report_busy(run_hold.race_message(run_hold.read_hold(target), target))
 }
@@ -145,11 +164,11 @@ function take_free_tree(target: string, issue: string): number {
 // record with a plain write would tell two sessions that both found it expired that they both won —
 // the race the free path was just fixed for, reintroduced one branch over. Removing it first is what
 // turns the expired record into a free tree; the create is what decides between the two claimants.
-function replace_stale(target: string, issue: string, hold: RunHold): number {
+function replace_stale(target: string, request: ClaimRequest, hold: RunHold): number {
 	console.error(run_hold.stale_message(hold))
 	run_hold.release_hold(target)
 
-	return take_free_tree(target, issue)
+	return take_free_tree(target, request)
 }
 
 // A non-clean preflight verdict is not an error: it is an answer a loop branches on, exactly as
@@ -176,8 +195,8 @@ async function preflight_gate(issue: string, is_linked: boolean): Promise<number
 	return report_preflight(decision)
 }
 
-async function claim(target: string, issue: string, is_linked: boolean): Promise<number> {
-	const gate = await preflight_gate(issue, is_linked)
+async function claim(target: string, request: ClaimRequest, is_linked: boolean): Promise<number> {
+	const gate = await preflight_gate(request.issue, is_linked)
 
 	if (gate !== undefined) return gate
 
@@ -187,7 +206,9 @@ async function claim(target: string, issue: string, is_linked: boolean): Promise
 	if (blocked !== undefined) return report_busy(blocked)
 
 	const code =
-		read.kind === 'stale' ? replace_stale(target, issue, read.hold) : take_free_tree(target, issue)
+		read.kind === 'stale'
+			? replace_stale(target, request, read.hold)
+			: take_free_tree(target, request)
 
 	if (code === SUCCESS_EXIT_CODE) await run_tidy_cli.sweep()
 
@@ -262,7 +283,7 @@ async function read_worktree(): Promise<string | undefined> {
 }
 
 async function dispatch(request: HoldRequest, target: string, is_linked: boolean): Promise<number> {
-	if (request.kind === 'claim') return await claim(target, request.issue, is_linked)
+	if (request.kind === 'claim') return await claim(target, request, is_linked)
 
 	if (request.kind === FORCE_RELEASE_KIND) return force_release(target)
 

package/scripts/run/run-hold.ts

@@ -43,6 +43,11 @@ interface RunHold {
 	issue: string
 	taken_at: string
 	pid: number
+	// Set only by `fullrun #N`'s entry (`run:entry` claims with `--fullrun`, joshuafolkken/kit#2760).
+	// The implementation cut outside a lane resumes as `fullrun #N`, so a `halfrun` or an in-session
+	// `backlogrun` child — which hold the tree just the same — must not be read as one. Optional and
+	// `| undefined` because a record written before this field existed is simply not a `fullrun`'s.
+	is_fullrun?: boolean | undefined
 }
 
 type HoldRead =
@@ -81,6 +86,7 @@ const run_hold_schema = z.object({
 	issue: z.string(),
 	taken_at: z.string(),
 	pid: z.number(),
+	is_fullrun: z.boolean().optional(),
 })
 
 // `undefined` for anything that is not a well-formed record, so the caller decides what a broken one
@@ -125,8 +131,8 @@ function read_hold(target: string, now: Date = new Date()): HoldRead {
 	return classify(stamp_file.read_stamp_text(target), now)
 }
 
-function build_hold(issue: string, now: Date): RunHold {
-	return { issue, taken_at: now.toISOString(), pid: process.pid }
+function build_hold(issue: string, now: Date, is_fullrun?: boolean): RunHold {
+	return { issue, taken_at: now.toISOString(), pid: process.pid, is_fullrun }
 }
 
 function write_hold(target: string, issue: string, now: Date = new Date()): RunHold {
@@ -141,8 +147,13 @@ function write_hold(target: string, issue: string, now: Date = new Date()): RunH
 // an entry point in the same second both read `free`, and a write would tell both of them they won —
 // which is the incident this guard was written after, reproduced by the guard itself. `false` means
 // the other one got there first.
-function create_hold(target: string, issue: string, now: Date = new Date()): boolean {
-	return stamp_file.create_stamp(target, build_hold(issue, now))
+function create_hold(
+	target: string,
+	issue: string,
+	now: Date = new Date(),
+	is_fullrun?: boolean,
+): boolean {
+	return stamp_file.create_stamp(target, build_hold(issue, now, is_fullrun))
 }
 
 // **A tree with uncommitted work in it is never handed over, however old its record is.** No age can

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

@@ -3,6 +3,7 @@ import { fileURLToPath } from 'node:url'
 import { parseArgs } from 'node:util'
 import { api_outage } from '#scripts/agent/api-outage'
 import { CONTEXT_CUT_THRESHOLD } from '#scripts/cost-runtime/context-cut-threshold'
+import { issue_closing_pr } from '#scripts/issue/issue-closing-pr'
 import { issue_state_cli } from '#scripts/issue/issue-state-cli'
 import { run_carry, type CarryOwner, type RunCarry } from './run-carry'
 import { run_ending } from './run-ending'
@@ -202,17 +203,27 @@ function read_is_outage(output: string | undefined): boolean {
 	return api_outage.is_outage(run_ending.read_exit(output))
 }
 
-async function read_signals(ctx: MergeContext): Promise<EndingSignals> {
-	return {
-		is_outage: read_is_outage(ctx.output),
-		is_cut: await run_merge_steps.has_resumable_cut(ctx.child),
-	}
+type IssueRead = Awaited<ReturnType<typeof issue_state_cli.read_issue>>
+
+// The timeline is read only for an OPEN, unparked child — the one classification a merged closing pull
+// request changes. A CLOSED child was closed by GitHub, so it must carry no `merged_pr` for
+// `do_merged` to close again (joshuafolkken/kit#2769).
+async function read_merged_pr(child: string, read: IssueRead): Promise<string | undefined> {
+	if (read.kind !== 'state' || run_merge.classify_child(read.state) !== 'failed') return undefined
+
+	return await issue_closing_pr.read_closing_pr(child)
 }
 
-function outcome_of(
-	read: Awaited<ReturnType<typeof issue_state_cli.read_issue>>,
-	signals: EndingSignals,
-): ChildOutcome {
+async function read_signals(ctx: MergeContext, read: IssueRead): Promise<EndingSignals> {
+	const [is_cut, merged_pr] = await Promise.all([
+		run_merge_steps.has_resumable_cut(ctx.child),
+		read_merged_pr(ctx.child, read),
+	])
+
+	return { is_outage: read_is_outage(ctx.output), is_cut, merged_pr }
+}
+
+function outcome_of(read: IssueRead, signals: EndingSignals): ChildOutcome {
 	return read.kind === 'state' ? run_merge.classify_child(read.state, signals) : 'unresolved'
 }
 
@@ -238,8 +249,8 @@ async function on_merged(ctx: MergeContext): Promise<MergeVerdict> {
 	return emit(await run_merge_steps.ask_next(ctx), SUCCESS_EXIT_CODE)
 }
 
-async function on_failed(ctx: MergeContext): Promise<MergeVerdict> {
-	const result = await run_merge_steps.do_failed(ctx)
+async function on_failed(ctx: MergeContext, cause?: string): Promise<MergeVerdict> {
+	const result = await run_merge_steps.do_failed(ctx, cause)
 
 	if (result.is_refused) return report_count_refused(result.carry)
 
@@ -291,7 +302,9 @@ async function on_cut(ctx: MergeContext): Promise<MergeVerdict> {
 
 	if (refused !== undefined) return report_count_refused(refused)
 
-	if (!(await run_merge_steps.resume_cut(ctx.child))) return await on_failed(ctx)
+	if (!(await run_merge_steps.resume_cut(ctx.child))) {
+		return await on_failed(ctx, run_merge_steps.CUT_RELAUNCH_CAUSE)
+	}
 
 	await run_event_stream_emit.emit(
 		run_event_stream.EVENT_KIND.CHILD_LAUNCH,
@@ -358,9 +371,10 @@ async function merge_child(ctx: MergeContext): Promise<MergeResult> {
 	}
 
 	const read = await issue_state_cli.read_issue(ctx.child, ctx.repo)
-	const outcome = outcome_of(read, await read_signals(ctx))
+	const signals = await read_signals(ctx, read)
+	const outcome = outcome_of(read, signals)
 
-	return { outcome, ...(await HANDLERS[outcome](ctx)) }
+	return { outcome, ...(await HANDLERS[outcome]({ ...ctx, merged_pr: signals.merged_pr })) }
 }
 
 async function run(argv: ReadonlyArray<string>): Promise<number> {

package/scripts/run/run-merge-steps.ts

@@ -1,5 +1,6 @@
 import { existsSync } from 'node:fs'
 import path from 'node:path'
+import { git_followup_issue_close } from '#scripts/git/git-followup-issue-close'
 import { git_gh_issue_write } from '#scripts/git/git-gh-issue-write'
 import { git_stash } from '#scripts/git/git-stash'
 import { IN_PROGRESS_LABEL, NEEDS_DECISION_LABEL } from '#scripts/git/issue-labels'
@@ -34,6 +35,12 @@ const LANES = '--lanes'
 const REPO_FLAG = '--repo'
 const LANE_CLOSE_OCCASION = 'lane close'
 const GIT_ENTRY = '.git'
+const MERGE_CLOSER = 'pnpm josh run:merge'
+const SINGLE_READ = { attempts: 1, interval_ms: 0 }
+// What the driver judged when it parks a child, stated on the issue (joshuafolkken/kit#2769).
+const FAILED_CAUSE = 'the child’s session ended with its issue still open and unfinished.'
+const CUT_RELAUNCH_CAUSE =
+	'its lane held a declared cut, but no successor could be relaunched from it (or it already was once).'
 
 // One returned child's context, gathered from the command line by the CLI.
 interface MergeContext {
@@ -46,6 +53,9 @@ interface MergeContext {
 	// ending apart from a genuine child failure (joshuafolkken/kit#2240); absent leaves outage detection
 	// off, so the child is classified from its GitHub state alone as before.
 	output?: string | undefined
+	// The merged pull request that closes the child, when GitHub left the child OPEN after the merge —
+	// the one `merged` child whose issue this command still has to close (joshuafolkken/kit#2769).
+	merged_pr?: string | undefined
 }
 
 interface FailedResult {
@@ -164,6 +174,22 @@ async function post_counters(ctx: MergeContext, carry: RunCarry | undefined): Pr
 	await git_gh_issue_write.issue_try_comment(ctx.epic, run_merge.counters_comment(carry))
 }
 
+// A child merged while GitHub left it OPEN is closed here, through the one close `followup` uses
+// (joshuafolkken/kit#2769). The state was just read OPEN, so it is read once rather than waited on. A
+// close that fails is reported with its recovery and does not undo the merge being counted.
+async function close_merged_open(ctx: MergeContext): Promise<void> {
+	if (ctx.merged_pr === undefined) return
+
+	try {
+		await git_followup_issue_close.ensure_issue_closed(
+			{ issue_number: ctx.child, pr_url: ctx.merged_pr, closer: MERGE_CLOSER },
+			SINGLE_READ,
+		)
+	} catch {
+		console.error(`#${ctx.child}: could not be closed — ${git_followup_issue_close.CLOSE_RECOVERY}`)
+	}
+}
+
 // A merged child: count the merge (which resets the failure streak), return to the default branch,
 // stash any uncommitted work the lane still holds and close it, and mirror the counters onto the epic. Returns the carry when the ownership check
 // fails — the caller treats a non-undefined return as a hard refusal and must not offer a next child
@@ -173,6 +199,7 @@ async function do_merged(ctx: MergeContext): Promise<RunCarry | undefined> {
 
 	if (refused !== undefined) return refused
 
+	await close_merged_open(ctx)
 	await sync_main()
 	const result = await apply_carry(ctx, {
 		...run_merge.change_of('merged'),
@@ -202,8 +229,10 @@ async function remove_in_progress(child: string): Promise<void> {
 // issue number forever, joshuafolkken/kit#2421), drop the stale `in-progress`, and park it with
 // `needs-decision` so the next offer does not hand the same child straight back. Returns the record
 // so the caller can read the streak against the guard. Returns `is_refused: true` without touching labels when the
-// carry record rejected the count (joshuafolkken/kit#2114).
-async function do_failed(ctx: MergeContext): Promise<FailedResult> {
+// carry record rejected the count (joshuafolkken/kit#2114). A park is always explained on the issue —
+// `cause` says what was judged, and the comment what was read and what a person does next
+// (joshuafolkken/kit#2769).
+async function do_failed(ctx: MergeContext, cause: string = FAILED_CAUSE): Promise<FailedResult> {
 	const result = await apply_carry(ctx, run_merge.change_of('failed'))
 
 	if (result.kind === 'refused') return { carry: result.carry, is_parked: false, is_refused: true }
@@ -214,6 +243,12 @@ async function do_failed(ctx: MergeContext): Promise<FailedResult> {
 	await remove_in_progress(ctx.child)
 	const is_parked = await git_gh_issue_write.issue_add_label(ctx.child, NEEDS_DECISION_LABEL)
 
+	if (is_parked) {
+		const reason = { child: ctx.child, cause, carry, output: ctx.output }
+
+		await git_gh_issue_write.issue_try_comment(ctx.child, run_merge.park_comment(reason))
+	}
+
 	return { carry, is_parked, is_refused: false }
 }
 
@@ -311,6 +346,7 @@ async function ask_next(ctx: MergeContext): Promise<string> {
 }
 
 const run_merge_steps = {
+	CUT_RELAUNCH_CAUSE,
 	apply_carry,
 	ask_next,
 	do_failed,

package/scripts/run/run-merge.ts

@@ -32,7 +32,9 @@ const ONE = 1
 
 // What a returned child turned out to be, decided from its GitHub state and — for the failed case
 // alone — the exit record.
-// - `merged`      — CLOSED; the child finished and its pull request merged.
+// - `merged`      — CLOSED; the child finished and its pull request merged. Also an OPEN, unparked
+//                   child a merged pull request's `closes #N` names — GitHub merged it without closing
+//                   the issue (joshuafolkken/kit#2769).
 // - `human-review` — OPEN and carrying `needs-human-review`; the run's own ending (SKILL.md → §2z).
 // - `parked`      — OPEN and carrying `needs-decision` or `already-done`; a person still owns it.
 // - `split`       — OPEN and carrying `epic`; its work was divided into new children.
@@ -60,6 +62,9 @@ type ChildOutcome =
 interface EndingSignals {
 	is_outage: boolean
 	is_cut: boolean
+	// The merged pull request whose `closes #N` names the child, when GitHub left the child OPEN after
+	// merging it (joshuafolkken/kit#2769).
+	merged_pr?: string | undefined
 }
 
 const NO_SIGNALS: EndingSignals = { is_outage: false, is_cut: false }
@@ -82,8 +87,12 @@ function is_parked(state: IssueState): boolean {
 // An OPEN, unparked child that is not waiting on a person: a declared cut is resumed
 // (joshuafolkken/kit#2484), and it is read before the outage so a cut whose process then lost the API is
 // still resumed from its record; an OPEN, unparked child that could not reach the API is an `outage`,
-// not a `failed` (joshuafolkken/kit#2240).
+// not a `failed` (joshuafolkken/kit#2240). **A merged pull request that closes it is read first**: the
+// work landed and only GitHub's close did not, so it is `merged` — never a failure counted against the
+// guard (joshuafolkken/kit#2769).
 function unfinished_outcome(signals: EndingSignals): ChildOutcome {
+	if (signals.merged_pr !== undefined) return 'merged'
+
 	if (signals.is_cut) return 'cut'
 
 	return signals.is_outage ? 'outage' : 'failed'
@@ -152,15 +161,44 @@ function counters_comment(carry: RunCarry): string {
 	].join('\n')
 }
 
+// Why the run parked a child it judged failed (joshuafolkken/kit#2769). A child that stops itself
+// leaves its own comment; one the driver stops left nothing, so a person opening the issue could not
+// tell why it carried `needs-decision`. Script-emitted, so English.
+interface ParkReason {
+	child: string
+	cause: string
+	carry: RunCarry | undefined
+	output: string | undefined
+}
+
+function streak_line(carry: RunCarry | undefined): string {
+	if (carry === undefined) return '- Consecutive failures: not recorded (no carry record).'
+
+	return `- Consecutive failures: ${String(carry.failures)} of ${String(CONSECUTIVE_FAILURE_LIMIT)} (the run stops at ${String(CONSECUTIVE_FAILURE_LIMIT)}).`
+}
+
+function park_comment(reason: ParkReason): string {
+	const transcript = reason.output === undefined ? '' : ` (\`${reason.output}\`)`
+
+	return [
+		'Parked with `needs-decision` by `pnpm josh run:merge`, the `backlogrun` driver — not by the child itself.',
+		`- Why: ${reason.cause}`,
+		'- Read: the issue is OPEN, carries none of `needs-decision`, `already-done`, `needs-human-review` or `epic`, and no merged pull request’s `closes #N` names it.',
+		streak_line(reason.carry),
+		`- Next: read the child’s transcript${transcript}, then either resume it with \`fullrun #${reason.child}\`, or record the decision here and remove \`needs-decision\`.`,
+	].join('\n')
+}
+
 const run_merge = {
 	CONSECUTIVE_FAILURE_LIMIT,
 	CONSECUTIVE_OUTAGE_LIMIT,
 	change_of,
 	classify_child,
 	counters_comment,
+	park_comment,
 	is_guard_tripped,
 	is_outage_guard_tripped,
 }
 
-export type { ChildOutcome, EndingSignals }
+export type { ChildOutcome, EndingSignals, ParkReason }
 export { run_merge }

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

@@ -6,10 +6,12 @@ import { issue_state_cli, type StateRead } from '#scripts/issue/issue-state-cli'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
 import { latest_scope_cli } from '#scripts/version/latest-scope-cli'
 import { run_prep, type PrepParts } from './run-prep'
+import { run_prep_locate } from './run-prep-locate'
 
 // `josh run:prep <N>` — one call for the reads a `fullrun` makes before its first edit
 // (joshuafolkken/kit#1978): the issue body and comments (`issue:read`), the state, labels and
-// `human_review` line (`issue:state`), and the dependency-update scope (`latest:scope`). Each is
+// `human_review` line (`issue:state`), the dependency-update scope (`latest:scope`), and where the
+// paths and identifiers the body names occur in code (`run-prep-locate.ts`). Each is
 // reused rather than reproduced, and the two body reads run concurrently, so three round trips become
 // one.
 //
@@ -37,6 +39,7 @@ interface PrepReads {
 	state: StateRead
 	latest: LatestDecision
 	has_changes: boolean
+	locations: string
 }
 
 // Exactly one issue number, or the call is refused: `run:prep` prepares one run, and a second number
@@ -90,8 +93,10 @@ async function gather(issue_number: string): Promise<PrepReads> {
 		issue_state_cli.read_issue(issue_number),
 		lane_has_changes(),
 	])
+	// Located from the body just read, so it waits for that read rather than joining the batch above.
+	const locations = await run_prep_locate.locate(content.kind === 'ok' ? content.block : '')
 
-	return { content, state, latest: latest_decision(), has_changes }
+	return { content, state, latest: latest_decision(), has_changes, locations }
 }
 
 function content_body(issue_number: string, content: BlockRead): string {
@@ -110,6 +115,7 @@ function to_parts(issue_number: string, reads: PrepReads): PrepParts {
 		latest_scope: reads.latest.scope,
 		latest_reason: reads.latest.reason,
 		has_changes: reads.has_changes,
+		locations: reads.locations,
 	}
 }
 

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

@@ -0,0 +1,165 @@
+import { get_exit_code } from '#scripts/git/git-execa-error'
+import { git_spawn } from '#scripts/git/git-spawn'
+
+// The code locations an issue names, bundled into `run:prep` (joshuafolkken/kit#2761). Across the 90
+// runs `.time-history.jsonl` split by contributor, 53% of round trips were investigation, and most of
+// it opened the files an issue names one read at a time. This finds each path, identifier and command
+// the body puts in backticks and hands back where it occurs in code — `file:line` and a short excerpt,
+// never a whole file — so the first read lands on the right place.
+//
+// **Only a backticked span is a target.** A prose word is not a name, and a span holding a space is a
+// command line or a sentence rather than one thing to look up; the one exception is a `josh` command,
+// whose subcommand is the name.
+
+const BACKTICKED = /`([^`\n]+)`/gu
+const JOSH_PREFIX = /^(?:pnpm\s+)?josh\s+(\S+)/u
+// A `file:line` citation names the file; the suffix would make both the file lookup and the grep miss.
+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)'
+// Code only, tests and snapshots excluded: a document mentions a name far more often than code
+// defines it, and the three-file cap would fill with prose before reaching the implementation.
+const CODE_PATHS = [
+	'*.ts',
+	'*.js',
+	'*.svelte',
+	':(exclude)*.test.ts',
+	':(exclude)*.e2e.ts',
+	':(exclude)*.snap',
+]
+
+interface Hit {
+	path: string
+	line: string
+	excerpt: string
+}
+
+interface Located {
+	target: string
+	hits: ReadonlyArray<Hit>
+	has_failed: boolean
+}
+
+function to_target(span: string): string {
+	const josh = JOSH_PREFIX.exec(span)
+
+	return josh?.[1] ?? span.trim().replace(LINE_SUFFIX, '')
+}
+
+function is_name(target: string): boolean {
+	if (target.length < MIN_TARGET_LENGTH || target.includes('://')) return false
+
+	return NAME_CHARACTERS.test(target) && NAME_SEPARATOR.test(target)
+}
+
+function extract_targets(text: string): Array<string> {
+	const targets = [...text.matchAll(BACKTICKED)].map((match) => to_target(match[1] ?? ''))
+
+	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}`
+
+	const lines = located.hits.map(
+		(hit) => `${INDENT}${hit.path}:${hit.line}${HIT_SEPARATOR}${hit.excerpt}`,
+	)
+
+	return [located.target, ...lines].join('\n')
+}
+
+function format_locations(located: ReadonlyArray<Located>): string {
+	if (located.length === 0) return NO_TARGETS
+
+	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.
+async function grep(target: string): Promise<Located> {
+	const grep_arguments = ['grep', '-n', '-I', '-F', '-m', '1', '-e', target, '--', ...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 }
+	}
+}
+
+// A path is rarely spelled out inside code — imports drop the extension and resolve relatively — so
+// grepping `scripts/run/run-prep.ts` misses the very file an issue most often names. A tracked file
+// whose path ends in the target is the location itself; `**/` lets a bare file name match too.
+async function find_files(target: string): Promise<Array<Hit>> {
+	try {
+		const stdout = await git_spawn.read(['ls-files', '--', `${FILE_PATHSPEC}${target}`])
+		const paths = stdout.split('\n').filter((path) => path !== '')
+
+		return paths.slice(0, MAX_FILES_PER_TARGET).map((path) => ({ path, ...FILE_HIT }))
+	} catch {
+		return []
+	}
+}
+
+async function find(target: string): Promise<Located> {
+	const files = await find_files(target)
+
+	if (files.length > 0) return { target, hits: files, has_failed: false }
+
+	return await grep(target)
+}
+
+async function locate(text: string): Promise<string> {
+	const located = await Promise.all(extract_targets(text).map(async (target) => await find(target)))
+
+	return format_locations(located)
+}
+
+const run_prep_locate = { extract_targets, format_locations, locate, parse_hits }
+
+export type { Hit, Located }
+export { run_prep_locate }

package/scripts/run/run-prep.ts

@@ -23,6 +23,7 @@ const NO = 'no'
 const CONTENT_HEADER = '=== issue ==='
 const STATE_HEADER = '=== state ==='
 const LATEST_HEADER = '=== dependency update ==='
+const LOCATIONS_HEADER = '=== code locations ==='
 const SECTION_SEPARATOR = '\n\n'
 const LATEST_JOINER = ' — '
 
@@ -35,6 +36,8 @@ interface PrepParts {
 	state_failure: string
 	latest_scope: string
 	latest_reason: string
+	// Where the paths and identifiers the issue names occur in code (joshuafolkken/kit#2761).
+	locations: string
 	// Whether a lane child's tree holds uncommitted work — read for the verdict, not printed in the
 	// report (joshuafolkken/kit#2476).
 	has_changes: boolean
@@ -75,10 +78,18 @@ function format_report(parts: PrepParts): string {
 		section(CONTENT_HEADER, parts.content_body),
 		section(STATE_HEADER, state_body(parts)),
 		section(LATEST_HEADER, `${parts.latest_scope}${LATEST_JOINER}${parts.latest_reason}`),
+		section(LOCATIONS_HEADER, parts.locations),
 	].join(SECTION_SEPARATOR)
 }
 
-const run_prep = { CONTENT_HEADER, LATEST_HEADER, STATE_HEADER, SUMMARY_PREFIX, format_report }
+const run_prep = {
+	CONTENT_HEADER,
+	LATEST_HEADER,
+	LOCATIONS_HEADER,
+	STATE_HEADER,
+	SUMMARY_PREFIX,
+	format_report,
+}
 
 export type { PrepParts }
 export { run_prep }