@joshuafolkken/kit 1.953.0 → 1.972.0

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 }

package/scripts/run/run-retrospective.ts

@@ -0,0 +1,34 @@
+import { hook_decision } from '#scripts/josh/hook-decision'
+
+// Whether a run owes its end-of-run retrospective, single-sourced so `run:step` and `backlog:drive`
+// never disagree on it (joshuafolkken/kit#2750): a drive that read "owed" where `run:step` read "not
+// owed" handed back at every drain to a session that had nothing to run.
+
+// The opt-in switch that gates the retrospective (joshuafolkken/kit#2370). It defaults off, so an unset
+// variable owes no retrospective.
+const RETROSPECTIVE_ENV_KEY = 'JOSH_RETROSPECTIVE'
+
+interface RetrospectiveFacts {
+	is_retrospective_enabled: boolean
+	is_lane_child: boolean
+	is_retrospective_done: boolean
+	is_consumer: boolean
+}
+
+function is_enabled(): boolean {
+	return hook_decision.is_switch_opt_in(RETROSPECTIVE_ENV_KEY)
+}
+
+// False when the switch is off, for a dispatched lane child (the batch runs one at its own end, never a
+// child's), once it has run this invocation, and in a consumer checkout, where the kit-only command is
+// refused. The switch is read first, so a run that has not opted in never consults the other three.
+function is_owed(facts: RetrospectiveFacts): boolean {
+	if (!facts.is_retrospective_enabled) return false
+
+	return !facts.is_lane_child && !facts.is_retrospective_done && !facts.is_consumer
+}
+
+const run_retrospective = { RETROSPECTIVE_ENV_KEY, is_enabled, is_owed }
+
+export type { RetrospectiveFacts }
+export { run_retrospective }

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

@@ -5,10 +5,13 @@ import { doctor_consumer } from '#scripts/doctor/doctor-consumer'
 import { hook_decision } from '#scripts/josh/hook-decision'
 import { find_package_directory } from '#scripts/josh/josh-logic'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
+import { lane_reap } from '#scripts/lane/lane-reap'
 import { run_carry, type CarryRead } from './run-carry'
 import { run_event_scope } from './run-event-scope'
 import { run_event_stream } from './run-event-stream'
+import { run_headless } from './run-headless'
 import { run_prep_cli } from './run-prep-cli'
+import { run_retrospective } from './run-retrospective'
 import { run_step, type StepInput } from './run-step'
 
 // `josh run:step <N>` — print the run's next single action, computed from the event stream, the carry
@@ -22,18 +25,25 @@ const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const ARGV_OFFSET = 2
 const USAGE = 'Usage: josh run:step <issue-number>'
-// The opt-in switch that gates the end-of-run retrospective (joshuafolkken/kit#2370). Read here rather
-// than in `run-step.ts` so the position logic stays a pure function of its input; it defaults off, so an
-// unset variable prints no retrospective step.
-const RETROSPECTIVE_ENV_KEY = 'JOSH_RETROSPECTIVE'
 
 interface RunReads {
 	carry_kind: CarryRead['kind']
 	is_retrospective_done: boolean
 	is_at_cut_cap: boolean
+	is_handed_off: boolean
 	last_event: string | undefined
 }
 
+// **A hand-off stops only the session that declared the record** (joshuafolkken/kit#2760). The record is
+// one per repository, so a `fullrun #M` a person starts in a fresh conversation beside a `backlogrun`
+// waiting for its successor reads the same handed-off mark — and would be told to stop on every step.
+// The owner is `--owner "$PPID"`, an ancestor of this process only in the session that took the cut.
+function is_handed_off_here(carry: CarryRead): boolean {
+	if (carry.kind !== 'carried' || carry.carry.is_handed_off !== true) return false
+
+	return run_headless.is_owned_here(carry.carry, lane_reap.own_ancestry)
+}
+
 // The run-level reads, keyed on the common git directory both the carry and the event stream share. A
 // directory that cannot be read leaves the position unknowable, which `next_action` answers `unknown`.
 function read_run(directory: string | undefined, issue_number: string): RunReads {
@@ -42,6 +52,7 @@ function read_run(directory: string | undefined, issue_number: string): RunReads
 			carry_kind: 'unreadable',
 			is_retrospective_done: false,
 			is_at_cut_cap: false,
+			is_handed_off: false,
 			last_event: undefined,
 		}
 	}
@@ -63,6 +74,7 @@ function read_run(directory: string | undefined, issue_number: string): RunReads
 		carry_kind: carry.kind,
 		is_retrospective_done: run_carry.retrospective_done_of(carry),
 		is_at_cut_cap: carry.kind === 'carried' && run_carry.is_at_cut_cap(carry.carry),
+		is_handed_off: is_handed_off_here(carry),
 		last_event: last?.kind,
 	}
 }
@@ -81,9 +93,11 @@ async function gather(issue_number: string): Promise<StepInput> {
 		carry_kind: run_reads.carry_kind,
 		is_retrospective_done: run_reads.is_retrospective_done,
 		is_at_cut_cap: run_reads.is_at_cut_cap,
+		is_handed_off: run_reads.is_handed_off,
 		is_lane_child: lane_child_marker.is_child_of(process.cwd()),
 		is_consumer: doctor_consumer.is_kit_consumer(find_package_directory(process.cwd())),
-		is_retrospective_enabled: hook_decision.is_switch_opt_in(RETROSPECTIVE_ENV_KEY),
+		// Read here rather than in `run-step.ts` so the position logic stays a pure function of its input.
+		is_retrospective_enabled: run_retrospective.is_enabled(),
 		has_changes: parts.has_changes,
 		has_completion_callback: agent_role_profile.has_completion_callback(),
 	}

package/scripts/run/run-step.ts

@@ -2,6 +2,7 @@ import { git_stash } from '#scripts/git/git-stash'
 import { latest_scope_cli } from '#scripts/version/latest-scope-cli'
 import type { CarryRead } from './run-carry'
 import { run_event_stream } from './run-event-stream'
+import { run_retrospective } from './run-retrospective'
 
 // `josh run:step <N>` — the run's next single action, computed from three mechanical inputs and nothing
 // else (joshuafolkken/kit#2248). It is the child of epic #2166 that lifts the fold from an *event* to a
@@ -125,6 +126,11 @@ interface StepInput extends PreInput {
 	// Whether the carried invocation has already taken its maximum cuts, read off the carry record by the
 	// CLI (joshuafolkken/kit#2346). At the cap `run:carry --cut` refuses, so the hand-off is not offered.
 	is_at_cut_cap: boolean
+	// Whether the carry record has been handed off by a cut and no successor has adopted it yet, read off
+	// the record by the CLI (joshuafolkken/kit#2760) and set only in the session that declared the record.
+	// The session that took the cut is the only one that can read this — a successor spends the mark when
+	// it begins — so it is what tells that session to stop.
+	is_handed_off: boolean
 }
 
 interface StepAction {
@@ -174,23 +180,10 @@ const EVENT_ACTIONS: Record<string, (issue_number: string) => StepAction> = {
 // (joshuafolkken/kit#2297).
 const PARENT_ONLY_EVENTS: ReadonlySet<string> = new Set([KIND.MERGE, KIND.OUTAGE])
 
-// Whether a run at a winding-down position still owes its end-of-run retrospective
-// (joshuafolkken/kit#2328) — false when the switch is off (the opt-in default, joshuafolkken/kit#2370),
-// for a dispatched lane child, where the batch runs one at its own end and never a child's (the
-// `release:scope` precedent), for a run whose retrospective has already run this invocation, and in a
-// consumer checkout, where the kit-only command is refused. The switch is read first, so a run that has
-// not opted in never consults the other three. The two positions that consult it are the drain and the
-// stop; both read exactly this, so the exclusion set is single-sourced.
-function is_retrospective_owed(input: StepInput): boolean {
-	if (!input.is_retrospective_enabled) return false
-
-	return !input.is_lane_child && !input.is_retrospective_done && !input.is_consumer
-}
-
 // A stopped run's last owed step is the end-of-run retrospective. When it is not owed the position stops
 // with no command to run, which is what the position meant before the retrospective existed.
 function stop_action(input: StepInput): StepAction {
-	return is_retrospective_owed(input) ? command(RETROSPECTIVE_COMMAND) : verdict(STOP)
+	return run_retrospective.is_owed(input) ? command(RETROSPECTIVE_COMMAND) : verdict(STOP)
 }
 
 // The drain fires the retrospective *before* the idle watch, not after it (joshuafolkken/kit#2335): the
@@ -199,7 +192,7 @@ function stop_action(input: StepInput): StepAction {
 // run proceeds to that watch, which is a `WAIT` rather than a `STOP`: the backlog is empty but the run is
 // not ending, and the real `STOP` follows when the watch expires with the retrospective already done.
 function drain_action(input: StepInput): StepAction {
-	return is_retrospective_owed(input) ? command(RETROSPECTIVE_COMMAND) : verdict(WAIT)
+	return run_retrospective.is_owed(input) ? command(RETROSPECTIVE_COMMAND) : verdict(WAIT)
 }
 
 // The hand-off a `backlogrun` parent without a completion callback takes right after dispatching
@@ -270,12 +263,31 @@ function closed_action(input: StepInput): StepAction {
 	}
 }
 
-// The terminal answers read before the run's position matters: an unreadable carry record leaves the
-// position unknowable, a spent budget is the person's call, and the issue's own state can end the run
-// whatever the events say. `undefined` when none applies and the position decides.
-function terminal_action(input: StepInput): StepAction | undefined {
+// **A cut hands the run on, so the session that took it stops** (joshuafolkken/kit#2760). The driver had
+// no handed-off state, so after `run:carry --cut` it went on answering `wait` or the next offer — a
+// `backlogrun` parent measured at 233k kept launching children in the same conversation up to 294k. A
+// lane child never holds the carry record, so its own position is not decided here.
+function is_handed_off_parent(input: StepInput): boolean {
+	return input.is_handed_off && input.carry_kind === 'carried' && !input.is_lane_child
+}
+
+// The carry record's terminal answers: an unreadable record leaves the position unknowable, a handed-off
+// run is its successor's, and a spent budget is the person's call.
+function carry_terminal_action(input: StepInput): StepAction | undefined {
 	if (input.carry_kind === 'unreadable') return verdict(UNKNOWN)
+	if (is_handed_off_parent(input)) return verdict(STOP)
 	if (input.carry_kind === 'expired') return { kind: 'decide', line: EXPIRED_DECISION }
+
+	return undefined
+}
+
+// The terminal answers read before the run's position matters: the carry record's first, then the
+// issue's own state, which can end the run whatever the events say. `undefined` when none applies and
+// the position decides.
+function terminal_action(input: StepInput): StepAction | undefined {
+	const carry_action = carry_terminal_action(input)
+
+	if (carry_action !== undefined) return carry_action
 	if (input.state === undefined) return verdict(UNKNOWN)
 	if (input.state === CLOSED) return closed_action(input)
 

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

@@ -33,8 +33,10 @@ interface Step {
 	argv: (issues: ReadonlyArray<string>) => ReadonlyArray<string>
 }
 
-// The steps in the order a run closes on: the ledger is committed first so the recurrence count is on
-// main, the citations are read for the completion report, and the release scope is decided last.
+// The steps in the order a run closes on: any ledger line the run's own commit did not carry
+// (joshuafolkken/kit#2763) is committed first so the recurrence count is on main — on most runs the
+// flush answers `clean` — the citations are read for the completion report, and the release scope is
+// decided last.
 const FLUSH_STEP: Step = {
 	header: run_tail.OBSERVATIONS_HEADER,
 	argv: () => ['observations:flush'],

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

@@ -29,6 +29,7 @@ import { run_invocation } from './run-invocation'
 const NO_FREE = 0
 const NO_READY = 0
 const SUCCESS_EXIT_CODE = 0
+const TRIAGE_WORK = 1
 
 interface WorkPorts {
 	// The free-lane count, or `undefined` where the lane limit could not be read.
@@ -41,6 +42,9 @@ async function real_ready_count(): Promise<number | undefined> {
 	const result = await josh_command.josh_run(['backlog:next'], true)
 
 	if (result.code !== SUCCESS_EXIT_CODE) return undefined
+	// A `triage` answer offers no number, but the untriaged issues are a session's to judge
+	// (joshuafolkken/kit#2779) — counted as one piece of work, or the whole pool would idle with nobody judging it.
+	if (backlog_stalled.needs_triage(result.out)) return TRIAGE_WORK
 
 	return backlog_stalled.count_ready_tokens(result.out)
 }

package/scripts/safe-chain/ci-installer-pin.ts

@@ -2,11 +2,15 @@ import { createHash } from 'node:crypto'
 import { existsSync, readFileSync, writeFileSync } from 'node:fs'
 import { execaSync } from 'execa'
 
-// The workflows that install safe-chain on the runner. Both carry the release and the installer's
+// The workflows that install safe-chain on the runner. Each carries the release and the installer's
 // SHA-256 as workflow-level env, so one pin per file moves every "Setup safe-chain" step at once
-// (joshuafolkken/kit#2711). A consumer has only the first, and `josh sync` rewrites it from the
-// template, so moving it anywhere but kit is harmless and short-lived.
-const WORKFLOW_PATHS = ['.github/workflows/ci.yml', 'templates/workflows/ci.yml']
+// (joshuafolkken/kit#2711, joshuafolkken/kit#2765). A consumer has the first and the last, and
+// `josh sync` rewrites both from kit, so moving them anywhere but kit is harmless and short-lived.
+const WORKFLOW_PATHS = [
+	'.github/workflows/ci.yml',
+	'templates/workflows/ci.yml',
+	'.github/workflows/pr-classification.yml',
+]
 // `[ \t]` rather than `\s`: under the `m` flag `\s*` would run across line ends and swallow the
 // blank line that follows the env block.
 const VERSION_RE = /^(?<key>[ \t]*SAFE_CHAIN_INSTALLER_VERSION:[ \t]*)(?<value>\S+)[ \t]*$/mu

package/scripts/time-runtime/time-background.ts

@@ -50,6 +50,8 @@ const NO_FINISH = 0
 // The launch's own result body, which is the only place the harness writes the id it assigns. Read
 // as a derived fact and the body discarded, exactly as `has_failure_line` and `followup_stages` are.
 const LAUNCH_PATTERN = /running in background with ID:\s*([\w-]+)/iu
+// A backgrounded subagent's launch result, which names its id on an `agentId:` line of its own.
+const AGENT_LAUNCH_PATTERN = /^Async agent launched[\s\S]*?\bagentId:\s*([\w-]+)/u
 // The notice the harness writes when a task it took into the background ends
 // (joshuafolkken/kit#1696). It is anchored at the start because the whole content of that line *is*
 // the notice — a body merely quoting one is text, the same hazard `read_id` unquotes for — and it
@@ -96,6 +98,14 @@ function launch_id(text: string): string {
 	return LAUNCH_PATTERN.exec(text)?.[1] ?? NO_BACKGROUND
 }
 
+// The id of a subagent the harness took into the background (joshuafolkken/kit#2774). Its end is the
+// same `<task-id>` notice a command's is, so `finished_id` pairs it unchanged. It is kept apart from
+// `launch_id` on purpose: a subagent is not a command, and folding it in would open a timeline window
+// that re-stamps the spans a backgrounded gate running beside the review is owed.
+function agent_launch_id(text: string): string {
+	return AGENT_LAUNCH_PATTERN.exec(text)?.[1] ?? NO_BACKGROUND
+}
+
 // The background run a task-notification line reports the end of, or nothing for every other line —
 // which is nearly all of them, since only one line kind in a transcript carries this notice.
 function finished_id(text: string): string {
@@ -288,6 +298,7 @@ const time_background = {
 	NO_BACKGROUND,
 	NO_FINISH,
 	launch_id,
+	agent_launch_id,
 	finished_id,
 	finished_at,
 	read_id,

package/scripts/time-runtime/time-transcript-line.ts

@@ -117,6 +117,9 @@ interface Block {
 	// it is what pairs a launch with the call that later reads its output, so the minutes the command
 	// actually ran can be placed on the timeline instead of only the seconds its launch call took.
 	background_id: string
+	// The id of a subagent this block launched into the background, and `''` for every other block
+	// (joshuafolkken/kit#2774) — apart from `background_id` so the timeline windows stay commands only.
+	agent_id: string
 }
 
 interface TranscriptLine {
@@ -183,6 +186,7 @@ function to_block(raw: z.infer<typeof BLOCK_SCHEMA>): Block {
 		error_text: is_error === true ? text.slice(0, ERROR_TEXT_LIMIT) : '',
 		refusal_guard: is_error === true ? guard_from_refusal(text) : '',
 		background_id: time_background.launch_id(text),
+		agent_id: time_background.agent_launch_id(text),
 	}
 }
 

package/templates/pnpm-workspace.static.yaml

@@ -1,4 +1,6 @@
 # Written by `josh init` for a static project (joshuafolkken/kit#2693). kit's CLI runs on tsx, which
 # depends on esbuild, and pnpm fails an install whose dependencies carry an unapproved build script.
+# unrs-resolver arrives through kit's optional ESLint import peers (joshuafolkken/kit#2785).
 allowBuilds:
   esbuild: true
+  unrs-resolver: true