@joshuafolkken/kit 1.957.0 → 1.978.0

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-step-cli.ts

@@ -5,9 +5,11 @@ 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'
@@ -28,9 +30,20 @@ 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 {
@@ -39,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,
 		}
 	}
@@ -60,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,
 	}
 }
@@ -78,6 +93,7 @@ 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())),
 		// Read here rather than in `run-step.ts` so the position logic stays a pure function of its input.

package/scripts/run/run-step.ts

@@ -126,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 {
@@ -258,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/security/security-audit.ts

@@ -86,10 +86,21 @@ function resolve_scanner(project_root: string, platform: string): ScannerChoice
 	return has_path_binary ? { path: BINARY_NAME, is_below_floor: true } : undefined
 }
 
+// **Output is forwarded, never handed the terminal itself.** osv-scanner is a Go binary that probes a
+// terminal on its stdout for its background color (an OSC 11 query followed by a cursor-position
+// request) and never reads the answers, so they sat in the terminal's input queue and surfaced at the
+// next shell prompt as `11;rgb:0101/0404/0909;1R` after a push ran this audit from the pre-push hook.
+// A pipe means the scanner sees no terminal and asks nothing; the `inherit` half still prints its report.
+// The fix belongs here, at the one command that asks, rather than on `git push`: piping the push would
+// make its timeout wait on any process a hook left running (joshuafolkken/kit#2801).
+const FORWARDED_OUTPUT = ['inherit', 'pipe'] as const
+
 function run_scanner(scanner_path: string): number {
 	const { LOCKFILE_PATH, build_scanner_arguments } = security_audit_logic
 	const result = execaSync(scanner_path, [...build_scanner_arguments(LOCKFILE_PATH)], {
-		stdio: 'inherit',
+		stdin: 'inherit',
+		stdout: FORWARDED_OUTPUT,
+		stderr: FORWARDED_OUTPUT,
 		reject: false,
 	})
 

package/scripts/sync/sync.ts

@@ -8,6 +8,7 @@ import { init_logic } from '#scripts/init/init-logic'
 import { PACKAGE_DIR, PROJECT_ROOT } from '#scripts/init/init-paths'
 import { plugin_install_hint_module } from '#scripts/init/plugin-install-hint'
 import { auto_merge_setting } from '#scripts/repo/auto-merge-setting'
+import { repository_labels } from '#scripts/repo/repository-labels'
 import { project_config } from '#scripts/safe-chain/project-config'
 import { security_updates } from '#scripts/security/security-updates'
 import { sonar_file } from '#scripts/security/sonar-file'
@@ -364,9 +365,14 @@ function sync_package_json_migrations(destination_path: string): void {
 // unless the repository allows auto-merge (joshuafolkken/kit#834). Neither ever fails the sync: both
 // are GitHub-side state, not synced artifacts. Unconditional, unlike `init`, because `sync`
 // overwrites both files on every run.
+//
+// The labels are the same kind of GitHub-side prerequisite, and one kit *can* write: the synced
+// `pr-classification.yml` requires one of the release classification labels, so the missing ones are
+// created here rather than reported (joshuafolkken/kit#2797).
 function report_repository_settings(name_with_owner: string | undefined): void {
 	security_updates.report_security_updates_section(name_with_owner)
 	auto_merge_setting.report_auto_merge_section(name_with_owner)
+	repository_labels.ensure_labels(name_with_owner)
 }
 
 function sync_project_artifacts(is_force: boolean): void {

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