@joshuafolkken/kit 1.1094.0 → 1.1136.0

package/scripts/backlog/backlog-budget-cli.ts

@@ -32,11 +32,7 @@ type ParsedValues = Partial<Record<OptionName, string | boolean>>
 // A misspelled flag is refused rather than defaulted, the contract `path_decision.has_unknown_flag`
 // states for the path-decided commands: an invocation nobody can read is never answered.
 function read_arguments(argv: ReadonlyArray<string>): ParsedValues | undefined {
-	return cli_flags.parse_or_undefined({ args: [...argv], options: OPTIONS, strict: true })?.values
-}
-
-function text_of(value: string | boolean | undefined): string | undefined {
-	return typeof value === 'string' ? value : undefined
+	return cli_flags.values_of(argv, OPTIONS)
 }
 
 // `find` rather than a cast: an unrecognized word has to be refused, and a type assertion would
@@ -79,15 +75,15 @@ type Counts = Record<(typeof COUNT_NAMES)[number], number | undefined>
 
 function counts_of(values: ParsedValues): Counts {
 	return {
-		idle: to_count(text_of(values.idle)),
-		max: to_count(text_of(values.max)),
-		merged: to_count(text_of(values.merged)),
-		running: to_count(text_of(values.running)),
+		idle: to_count(cli_flags.string_of(values.idle)),
+		max: to_count(cli_flags.string_of(values.max)),
+		merged: to_count(cli_flags.string_of(values.merged)),
+		running: to_count(cli_flags.string_of(values.running)),
 	}
 }
 
 function are_counts_readable(values: ParsedValues, counts: Counts): boolean {
-	return COUNT_NAMES.every((name) => is_readable(text_of(values[name]), counts[name]))
+	return COUNT_NAMES.every((name) => is_readable(cli_flags.string_of(values[name]), counts[name]))
 }
 
 // **`--idle 0` is how the watch is turned off, and omitting the flag takes the default**
@@ -116,14 +112,17 @@ function to_idle_ms(idle_minutes: number | undefined): number | undefined {
 // lands on the very first ask, before the run has started anything, and the fix is one flag the loop
 // already holds: it always knows when it last had work.
 function is_watch_readable(values: ParsedValues): boolean {
-	if (to_idle_ms(to_count(text_of(values.idle))) === undefined) return true
+	if (to_idle_ms(to_count(cli_flags.string_of(values.idle))) === undefined) return true
 
-	return text_of(values.active) !== undefined
+	return cli_flags.string_of(values.active) !== undefined
 }
 
 function are_values_readable(values: ParsedValues): boolean {
 	return (
-		is_readable(text_of(values.active), to_time_ms(text_of(values.active))) &&
+		is_readable(
+			cli_flags.string_of(values.active),
+			to_time_ms(cli_flags.string_of(values.active)),
+		) &&
 		is_watch_readable(values) &&
 		are_counts_readable(values, counts_of(values))
 	)
@@ -138,7 +137,7 @@ function input_of(values: ParsedValues, base: InputBase): BudgetInput {
 
 	return {
 		...base,
-		active_at_ms: to_time_ms(text_of(values.active)) ?? base.started_at_ms,
+		active_at_ms: to_time_ms(cli_flags.string_of(values.active)) ?? base.started_at_ms,
 		merged: counts.merged ?? 0,
 		running: counts.running ?? 0,
 		max_issues: counts.max,
@@ -147,11 +146,11 @@ function input_of(values: ParsedValues, base: InputBase): BudgetInput {
 }
 
 function build_input(values: ParsedValues, now_ms: number): BudgetInput | undefined {
-	const answer = to_answer(text_of(values.answer))
+	const answer = to_answer(cli_flags.string_of(values.answer))
 
 	if (answer === undefined) return undefined
 
-	const started_at_ms = to_time_ms(text_of(values.started))
+	const started_at_ms = to_time_ms(cli_flags.string_of(values.started))
 
 	if (started_at_ms === undefined) return undefined
 	if (!are_values_readable(values)) return undefined

package/scripts/backlog/backlog-offer-cli.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
-import { parseArgs } from 'node:util'
 import { josh_command } from '#scripts/josh/josh-run'
+import { cli_flags } from '#scripts/lib/cli-flags'
 import { rule_value_cache } from '#scripts/rules/rule-value-cache'
 import { run_event_stream } from '#scripts/run/run-event-stream'
 import { run_event_stream_emit } from '#scripts/run/run-event-stream-emit'
@@ -61,15 +61,7 @@ type ParsedValues = Partial<Record<OptionName, string | boolean | ReadonlyArray<
 const FORWARDED = ['started', 'active', 'merged', 'running', 'max', 'idle'] as const
 
 function read_values(argv: ReadonlyArray<string>): ParsedValues | undefined {
-	try {
-		return parseArgs({ args: [...argv], options: OPTIONS, strict: true }).values
-	} catch {
-		return undefined
-	}
-}
-
-function text_of(value: string | boolean | ReadonlyArray<string> | undefined): string | undefined {
-	return typeof value === 'string' ? value : undefined
+	return cli_flags.values_of(argv, OPTIONS)
 }
 
 function to_count(raw: string | undefined): number | undefined {
@@ -94,8 +86,8 @@ interface OfferCounts {
 // The two counts the mapping needs: `--running` decides `wait`, `--retries` decides `retry`. Either
 // given but unreadable refuses the whole invocation.
 function counts_of(values: ParsedValues): OfferCounts | undefined {
-	const running = count_of(text_of(values.running), DEFAULT_COUNT)
-	const retries = count_of(text_of(values.retries), DEFAULT_COUNT)
+	const running = count_of(cli_flags.string_of(values.running), DEFAULT_COUNT)
+	const retries = count_of(cli_flags.string_of(values.retries), DEFAULT_COUNT)
 
 	if (running === undefined || retries === undefined) return undefined
 
@@ -109,7 +101,7 @@ function excludes_of(values: ParsedValues): ReadonlyArray<string> {
 }
 
 function next_argv(values: ParsedValues): ReadonlyArray<string> {
-	const repo = text_of(values.repo)
+	const repo = cli_flags.string_of(values.repo)
 
 	return [
 		'backlog:next',
@@ -120,7 +112,7 @@ function next_argv(values: ParsedValues): ReadonlyArray<string> {
 
 function budget_argv(values: ParsedValues, answer: string): ReadonlyArray<string> {
 	const forwarded = FORWARDED.flatMap((name) => {
-		const value = text_of(values[name])
+		const value = cli_flags.string_of(values[name])
 
 		return value === undefined ? [] : [`--${name}`, value]
 	})

package/scripts/backlog/backlog-plan.ts

@@ -3,6 +3,7 @@ import type { IssueReference } from '#scripts/epic/epic-reference'
 import { epic_report, type EpicNextResult } from '#scripts/epic/epic-report'
 import { epic_solo } from '#scripts/epic/epic-solo'
 import { epic_triage } from '#scripts/epic/epic-triage'
+import { issue_cite } from '#scripts/issue/issue-cite'
 import { has_label_name, IN_PROGRESS_LABEL, RUN_SOLO_LABEL } from '#scripts/issue/issue-labels'
 import type { OutOfScopeRow } from './backlog-scope'
 
@@ -57,23 +58,29 @@ interface PlanContext {
 
 // A child elsewhere is qualified, because a bare number would name *this* repository's issue of that
 // number — a different issue (joshuafolkken/kit#1016). Takes the reference rather than the child, so
-// a `blocked_by` edge is named by the same rule the child itself is.
-function reference_of(reference: IssueReference, repo: string): string {
+// a `blocked_by` edge is named by the same rule the child itself is. This repository's issue is cited
+// (joshuafolkken/kit#3099): the plan is copied into a report verbatim, so the line it prints is the
+// citation the report carries.
+function cite_of(reference: IssueReference, repo: string, title: string | undefined): string {
 	const number = String(reference.number)
 
-	return reference.repo === repo ? `#${number}` : `${reference.repo}#${number}`
+	return reference.repo === repo
+		? issue_cite.reference(repo, number, title)
+		: `${reference.repo}#${number}`
+}
+
+function reference_of(reference: IssueReference, repo: string): string {
+	return cite_of(reference, repo, undefined)
 }
 
 // A title is only known for this repository's issues — the open listing the titles come from is this
 // repository's. A child elsewhere is still named, just without one.
-function title_of(child: EpicChild, context: PlanContext): string {
-	return child.repo === context.repo ? (context.titles.get(child.number) ?? '') : ''
+function title_of(child: EpicChild, context: PlanContext): string | undefined {
+	return child.repo === context.repo ? context.titles.get(child.number) : undefined
 }
 
-function join_row(reference: string, title: string, note: string): string {
-	const parts = [reference, title, note === '' ? '' : `— ${note}`].filter((part) => part !== '')
-
-	return `${ROW_INDENT}${parts.join('  ')}`
+function join_row(reference: string, note: string): string {
+	return note === '' ? `${ROW_INDENT}${reference}` : `${ROW_INDENT}${reference}  — ${note}`
 }
 
 // A `run:solo` child is marked beside its number, so a person reading the plan sees which issues
@@ -89,15 +96,15 @@ function mark_of(child: EpicChild): string | undefined {
 	return epic_triage.is_triaged(child) ? undefined : UNTRIAGED_MARK
 }
 
-function marked_reference(child: EpicChild, repo: string): string {
-	const reference = reference_of(child, repo)
+function marked_reference(child: EpicChild, repo: string, title?: string): string {
+	const reference = cite_of(child, repo, title)
 	const mark = mark_of(child)
 
 	return mark === undefined ? reference : `${reference} ${mark}`
 }
 
 function row_of(child: EpicChild, context: PlanContext, note: string): string {
-	return join_row(marked_reference(child, context.repo), title_of(child, context), note)
+	return join_row(marked_reference(child, context.repo, title_of(child, context)), note)
 }
 
 // Why this one is not offered yet. The blocker numbers are the answer whenever there are any — that
@@ -164,8 +171,10 @@ function waiting_lines(children: ReadonlyArray<EpicChild>, context: PlanContext)
 	})
 }
 
-function scope_lines(rows: ReadonlyArray<OutOfScopeRow>): Array<string> {
-	return rows.map((row) => join_row(`#${String(row.number)}`, row.title, row.reason))
+function scope_lines(rows: ReadonlyArray<OutOfScopeRow>, repo: string): Array<string> {
+	return rows.map((row) =>
+		join_row(issue_cite.reference(repo, String(row.number), row.title), row.reason),
+	)
 }
 
 // The classification could not be made, so every section below it would be rendered from buckets
@@ -186,10 +195,12 @@ interface NamedPlan {
 	only: boolean
 }
 
-// The named issues are this repository's own, so a bare `#N` names them and a title is looked up the
-// same way the pool's rows are. The order is the invocation's, never sorted.
+// The named issues are this repository's own, so they are cited against it and a title is looked up
+// the same way the pool's rows are. The order is the invocation's, never sorted.
 function named_lines(named: ReadonlyArray<number>, context: PlanContext): Array<string> {
-	return named.map((issue) => join_row(`#${String(issue)}`, context.titles.get(issue) ?? '', ''))
+	return named.map((issue) =>
+		join_row(issue_cite.reference(context.repo, String(issue), context.titles.get(issue)), ''),
+	)
 }
 
 // The section leads the plan when the invocation named issues, and is absent otherwise — a bare
@@ -230,7 +241,7 @@ function format_plan(
 		'',
 		section(HUMAN_HEADING, child_lines(result.blocked_on_people, context, no_note)),
 		'',
-		section(SCOPE_HEADING, scope_lines(out_of_scope)),
+		section(SCOPE_HEADING, scope_lines(out_of_scope, context.repo)),
 	].join('\n')
 }
 

package/scripts/backlog/backlog-ready.ts

@@ -1,3 +1,5 @@
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { issue_cite } from '#scripts/issue/issue-cite'
 import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
 import { lane_capacity } from '#scripts/lane/lane-capacity'
 import { lane_registry } from '#scripts/lane/lane-registry'
@@ -92,35 +94,46 @@ async function read_ready(ports: ReadyPorts = DEFAULT_PORTS): Promise<ReadyReadi
 	return { issues: await ports.ready_issues(), free_lanes }
 }
 
-// `undefined` unless there is both runnable work and a lane for it — the only state worth a line.
-function ready_line(reading: ReadyReading): string | undefined {
+// `undefined` unless there is both runnable work and a lane for it — the only state worth a line. Each
+// issue is a number-link against `slug` (joshuafolkken/kit#3099): the parent copies this line into its
+// report, so a bare `#N` here is the citation the Stop guard sends back.
+function ready_line(reading: ReadyReading, slug: string | undefined): string | undefined {
 	if (reading.issues.length === NONE || reading.free_lanes <= NO_FREE) return undefined
 
-	const issues = reading.issues.map((issue) => `#${issue}`).join(' ')
+	const cite = issue_cite.citer(slug, new Map())
+	const issues = reading.issues.map((issue) => cite(issue)).join(' ')
 
 	return `ready ${issues} · free lanes ${String(reading.free_lanes)}`
 }
 
+type RepoRead = () => Promise<string | undefined>
+
 // The watcher's line on exit, for the driving parent alone — a `fullrun` watcher has no pool to pick
 // from. Best-effort: a reading that fails prints nothing rather than failing the watcher whose exit is
 // the wake.
 async function parent_ready_line(
 	ports: ReadyPorts,
 	is_parent: () => Promise<boolean>,
+	read_repo: RepoRead,
 ): Promise<string | undefined> {
 	if (!(await is_parent())) return undefined
 
-	return ready_line(await read_ready(ports))
+	const reading = await read_ready(ports)
+
+	return reading.issues.length === NONE ? undefined : ready_line(reading, await read_repo())
+}
+
+function print_line(line: string | undefined): void {
+	if (line !== undefined) console.info(line)
 }
 
 async function print_ready_line(
 	ports: ReadyPorts = DEFAULT_PORTS,
 	is_parent: () => Promise<boolean> = run_headless.is_backlog_parent,
+	read_repo: RepoRead = git_gh_command.repo_get_name_with_owner,
 ): Promise<void> {
 	try {
-		const line = await parent_ready_line(ports, is_parent)
-
-		if (line !== undefined) console.info(line)
+		print_line(await parent_ready_line(ports, is_parent, read_repo))
 	} catch {
 		// A pick-up line is a hint; the wake it rides must still be delivered.
 	}

package/scripts/config-merge/parse-jsonc.ts

@@ -1,14 +1,44 @@
 import { json_object_schema } from '#scripts/lib/schemas'
-import strip_json_comments from 'strip-json-comments'
+import { parseTree, printParseErrorCode, type Node, type ParseError } from 'jsonc-parser'
 
 // Every managed JSON config kit reads (tsconfig.json, package.json, .vscode/*.json) may legally
 // carry comments and trailing commas — TypeScript and VS Code both parse them as JSONC — so a plain
 // `JSON.parse` would throw on files consumers hand-authored. Single-sourced here because the
 // config-merge library and the init/sync merge helpers both need the exact same tolerant read.
+
+// Built from the tree rather than with jsonc-parser's own `parse` / `getNodeValue`, which assign each
+// key: a `"__proto__"` key would become the object's prototype instead of the own property
+// `JSON.parse` keeps, and the spread-and-stringify write-back would then drop it from the file.
+// `Object.fromEntries` defines properties, so every key stays data.
+function property_key(property: Node): string {
+	return String(property.children?.[0]?.value)
+}
+
+function node_value(node: Node | undefined): unknown {
+	if (node === undefined) return undefined
+	const children = node.children ?? []
+	if (node.type === 'array') return children.map((child) => node_value(child))
+	if (node.type !== 'object') return node.value
+
+	return Object.fromEntries(
+		children.map((property) => [property_key(property), node_value(property.children?.[1])]),
+	)
+}
+
+// jsonc-parser recovers from errors and returns a best-effort tree, so any reported error is
+// rethrown: a malformed document must fail the read the way `JSON.parse` would, not merge partially.
 function parse_jsonc(content: string): Record<string, unknown> {
-	const stripped = strip_json_comments(content, { trailingCommas: true })
+	const errors: Array<ParseError> = []
+	const tree = parseTree(content, errors, { allowTrailingComma: true })
+	const [first_error] = errors
+
+	if (first_error !== undefined) {
+		throw new SyntaxError(
+			`Invalid JSONC: ${printParseErrorCode(first_error.error)} at offset ${String(first_error.offset)}`,
+		)
+	}
 
-	return json_object_schema.parse(JSON.parse(stripped))
+	return json_object_schema.parse(node_value(tree))
 }
 
 export { parse_jsonc }

package/scripts/config-merge/patch-json-key.ts

@@ -1,5 +1,11 @@
-import { createScanner, findNodeAtLocation, getNodeValue, parseTree, type Node } from 'jsonc-parser'
-import strip_json_comments from 'strip-json-comments'
+import {
+	createScanner,
+	findNodeAtLocation,
+	getNodeValue,
+	parseTree,
+	stripComments,
+	type Node,
+} from 'jsonc-parser'
 import { json_format } from './json-format'
 
 // Set or remove one top-level key while leaving every other byte of the document alone.
@@ -163,13 +169,14 @@ function target_value_end(property: Node | undefined): number | undefined {
 	return value_node === undefined ? undefined : value_node.offset + value_node.length
 }
 
-// Whether the span holds a comment. `strip_json_comments` blanks comments while preserving length
-// and is string-aware, so a `//` inside a string value is not counted — a scanner-based check would
-// need `SyntaxKind`, which is an ambient const enum this project cannot import.
+// Whether the span holds a comment. `stripComments` drops every comment token the scanner finds, so
+// it changes the text exactly when a comment is present, and a `//` inside a string value is not
+// counted — comparing token kinds directly would need `SyntaxKind`, an ambient const enum this
+// project cannot import.
 function contains_comment(content: string, node: Node): boolean {
 	const text = content.slice(node.offset, node.offset + node.length)
 
-	return strip_json_comments(text) !== text
+	return stripComments(text) !== text
 }
 
 // Re-lay-out a property whose trailing comma has just appeared or disappeared. That one column

package/scripts/cost-runtime/cost-cli.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
-import { parseArgs } from 'node:util'
 import { agent_role_profile, type AgentProvider } from '#scripts/agent/agent-role-profile'
+import { cli_flags } from '#scripts/lib/cli-flags'
 import { codex_usage } from './codex-usage'
 import { CONTEXT_CUT_THRESHOLD } from './context-cut-threshold'
 import { cost_corpus } from './cost-corpus'
@@ -103,13 +103,9 @@ const PARSE_ARGS_OPTIONS = {
 } as const
 
 function parse_options(argv: ReadonlyArray<string>): Options | undefined {
-	try {
-		const { values } = parseArgs({ args: [...argv], options: PARSE_ARGS_OPTIONS, strict: true })
+	const values = cli_flags.values_of(argv, PARSE_ARGS_OPTIONS)
 
-		return to_options(values)
-	} catch {
-		return undefined
-	}
+	return values === undefined ? undefined : to_options(values)
 }
 
 // An empty corpus is reported, never priced at zero. "No transcript was found" and "this run was

package/scripts/delegation/delegation-policy.ts

@@ -32,6 +32,13 @@ interface DelegatableStep {
 // wait per turn — and below the threshold that round trip costs more than carrying the text.
 const INVESTIGATION_FILE_THRESHOLD = 3
 
+// The same boundary for searches, counted in turns (joshuafolkken/kit#3139). A `grep` carries no file
+// text, so it never reached the file count — yet across 100 lane transcripts on 2026-10-04, 424 turns
+// were searches alone and 160 of them came third or later since the last edit or delegation, each
+// re-reading the whole main-line context. Three keeps the first two searches, which locate an edit
+// target, in the main line and sends the continuing sweep to a unit.
+const INVESTIGATION_SEARCH_TURN_THRESHOLD = 3
+
 // The enumeration. Short on purpose: every entry had to name a verifier, and most candidates could
 // not (below).
 const DELEGATABLE_STEPS: ReadonlyArray<DelegatableStep> = [
@@ -88,7 +95,7 @@ const DELEGATABLE_STEPS: ReadonlyArray<DelegatableStep> = [
 		// verifiers differ, so widening `survey` would put both in one field and lose the boundary below.
 		// **No ordinal.** `${N}rd` would print `1rd` for any other threshold, past a test that only looks
 		// for the numeral, so the count is phrased as a plain "N or more".
-		does: `read the Issue's subject to find out how it currently works — once ${String(INVESTIGATION_FILE_THRESHOLD)} or more files the run will not edit have to be read — and return the conclusion plus the \`file:line\` citations that support it, never the file text, which would put the cost back where it was. A throwaway probe script is written, run and deleted inside the unit, which returns its output alone`,
+		does: `read the Issue's subject to find out how it currently works — once ${String(INVESTIGATION_FILE_THRESHOLD)} or more files the run will not edit have to be read, or ${String(INVESTIGATION_SEARCH_TURN_THRESHOLD)} or more search turns run without an edit — and return the conclusion plus the \`file:line\` citations that support it, never the file text, which would put the cost back where it was. A throwaway probe script is written, run and deleted inside the unit, which returns its output alone`,
 		verifier:
 			'the parent opens the cited lines; a conclusion those lines do not support fails there, and reading a handful of cited regions costs far less than redoing the reading. The unit reports what the code does and never what to change — deciding that is `diagnosis`, which stays kept, so a unit returning a root cause would be delegating the rejected row under this name',
 	},
@@ -176,6 +183,7 @@ function reason_for(name: string): string {
 const delegation_policy = {
 	DELEGATE_VERDICT,
 	INVESTIGATION_FILE_THRESHOLD,
+	INVESTIGATION_SEARCH_TURN_THRESHOLD,
 	KEEP_VERDICT,
 	DELEGATABLE_STEPS,
 	REJECTED_STEPS,

package/scripts/delegation/investigation-guard.ts

@@ -72,7 +72,7 @@ function should_notify(
 // (joshuafolkken/kit#2138, joshuafolkken/kit#2382). A dispatched lane child ends its turn on a denial, so
 // the same guidance is carried without a `permissionDecision`: the read proceeds and the child is nudged
 // to delegate rather than killed. It carries no ⛔, so a person watching reads it as advice.
-const NOTICE = `💡 investigation: files read and not edited since the last delegated unit reached the threshold, so the reading from here should go to a unit of its own. This is a notice, not a refusal — the read proceeds, because a dispatched lane child ends its turn on a denial. Ask \`pnpm josh delegate investigation\`, then brief a unit with what the main line has already concluded and what is left to find out; it returns the conclusion plus its \`file:line\` citations, never the file text. Keep a read in the main line only where this run will edit that file. This recurs on the next accumulation.`
+const NOTICE = `💡 investigation: files read and not edited, or search turns, since the last delegated unit reached the threshold, so the reading from here should go to a unit of its own. This is a notice, not a refusal — the read proceeds, because a dispatched lane child ends its turn on a denial. Ask \`pnpm josh delegate investigation\`, then dispatch the \`${investigation_reads.INVESTIGATOR_AGENT}\` agent (\`kit:${investigation_reads.INVESTIGATOR_AGENT}\` in a consumer) with a brief of what the main line has already concluded and what is left to find out; it returns the conclusion plus its \`file:line\` citations, never the file text. Keep a read in the main line only where this run will edit that file. This recurs on the next accumulation.`
 
 // The notice as it reaches the model: the base guidance with the concrete unedited reads named (kit#2276,
 // kit#2382), so a lane child is shown *which* reads to send to a unit rather than only told to delegate —