@joshuafolkken/kit 1.1178.0 → 1.1229.0

package/scripts/issue/issue-file-cli.ts

@@ -9,6 +9,7 @@ import { git_gh_issue_list, MAX_SCANNED } from '#scripts/gh/git-gh-issue-list'
 import { git_gh_issue_write } from '#scripts/gh/git-gh-issue-write'
 import { github_issue_url } from '#scripts/gh/github-issue-url'
 import { error_text } from '#scripts/lib/error-message'
+import type { PollOptions } from '#scripts/lib/poll'
 import { repository_labels } from '#scripts/repo/repository-labels'
 import { issue_auto_ok } from './issue-auto-ok'
 import { issue_file, type FileArguments } from './issue-file'
@@ -19,9 +20,10 @@ import { issue_wip } from './issue-wip'
 // `josh issue:file "<title>" --body-file <path> --depth <0|1|2> [--route <route>] [--label <name>]…
 // [--repo <owner/repo>] [--distinct <N,…>] [--over-cap] [--no-auto-ok]` — file an Issue with every
 // filing step run in order (joshuafolkken/kit#2808): the third-party refusal, the body lint, the
-// `## Origin` check for another repository, the WIP cap count (joshuafolkken/kit#3181), the duplicate
-// scout, the missing workflow labels created (joshuafolkken/kit#3176), the `auto-ok` decision
-// (joshuafolkken/kit#3213), the create call carrying every label, and `epic:bundle` after it.
+// `## Origin` check for another repository, the `auto-ok` decision (joshuafolkken/kit#3213) with the
+// run label it owes (joshuafolkken/kit#3313), the WIP cap count (joshuafolkken/kit#3181), the duplicate
+// scout, the missing workflow labels created (joshuafolkken/kit#3176), the create call carrying every
+// label, and `epic:bundle` after it.
 // A direct `gh api …/issues` filing is refused by the `direct-filing` delivered rule and pointed here.
 
 const SUCCESS_EXIT_CODE = 0
@@ -36,6 +38,9 @@ const THIRD_PARTY_MESSAGE =
 // `GH_REPO` is the variable `gh` reads `{owner}/{repo}` from, so setting it points every listing the
 // scout and `epic:bundle` make at the target repository rather than at this checkout.
 const GH_REPO_VARIABLE = 'GH_REPO'
+// The open listing `epic:bundle` reads trails the create call, so the issue just filed is looked for
+// again for up to ten seconds before the placement is given up (joshuafolkken/kit#3332).
+const FRESH_ISSUE_POLL: PollOptions = { attempts: 6, interval_ms: 2000 }
 
 interface Filing {
 	args: FileArguments
@@ -130,11 +135,9 @@ async function is_scout_clear(filing: Filing): Promise<boolean> {
 	return open.length === 0
 }
 
-// `undefined` when the create call failed. `gh`'s standard error is captured into the thrown error
-// rather than printed, so it is printed here — otherwise the filing fails with no reason given. A label
-// the create applies is provisioned first, so it never arrives with a generated color.
-async function create(filing: Filing): Promise<string | undefined> {
-	repository_labels.ensure_labels(filing.target)
+// Every label the create call carries, or `undefined` when an `auto-ok` filing names neither run label
+// (joshuafolkken/kit#3313). Decided before the WIP count and the scout, so a refusal costs no listing.
+async function labels_of(filing: Filing): Promise<ReadonlyArray<string> | undefined> {
 	const auto_ok = await issue_auto_ok.resolve(
 		filing.args.is_auto_ok_opted_out,
 		filing.target,
@@ -142,10 +145,24 @@ async function create(filing: Filing): Promise<string | undefined> {
 	)
 
 	console.info(issue_auto_ok.line_of(auto_ok))
+	const labels = issue_file.labels_of(filing.args, filing.body, auto_ok.is_applied)
+	const problem = issue_file.triage_problem(labels)
+
+	if (problem === undefined) return labels
+	console.error(`✖ ${problem}`)
+
+	return undefined
+}
+
+// `undefined` when the create call failed. `gh`'s standard error is captured into the thrown error
+// rather than printed, so it is printed here — otherwise the filing fails with no reason given. A label
+// the create applies is provisioned first, so it never arrives with a generated color.
+async function create(filing: Filing, labels: ReadonlyArray<string>): Promise<string | undefined> {
+	repository_labels.ensure_labels(filing.target)
 	const request = git_gh_issue_write.issue_create_request({
 		title: filing.args.title,
 		body: filing.body,
-		labels: issue_file.labels_of(filing.args, filing.body, auto_ok.is_applied),
+		labels,
 		repo: filing.target,
 	})
 
@@ -165,7 +182,7 @@ async function create(filing: Filing): Promise<string | undefined> {
 async function place(url: string, target: string): Promise<void> {
 	const issue_number = Number(github_issue_url.parse(url)?.issue_number)
 	const exit_code = Number.isSafeInteger(issue_number)
-		? await epic_bundle_cli.report_for(issue_number, target)
+		? await epic_bundle_cli.report_for(issue_number, target, FRESH_ISSUE_POLL)
 		: FAILURE_EXIT_CODE
 
 	if (exit_code !== SUCCESS_EXIT_CODE) {
@@ -173,17 +190,17 @@ async function place(url: string, target: string): Promise<void> {
 	}
 }
 
-async function file(filing: Filing): Promise<number> {
+function is_admitted(filing: Filing): boolean {
 	const refusals = refusals_of(filing)
 
-	if (refusals.length > 0) {
-		console.error(refusals.join('\n'))
+	if (refusals.length === 0) return true
+	console.error(refusals.join('\n'))
 
-		return FAILURE_EXIT_CODE
-	}
+	return false
+}
 
-	if (!(await is_wip_clear(filing)) || !(await is_scout_clear(filing))) return FAILURE_EXIT_CODE
-	const url = await create(filing)
+async function send(filing: Filing, labels: ReadonlyArray<string>): Promise<number> {
+	const url = await create(filing, labels)
 
 	if (url === undefined) return FAILURE_EXIT_CODE
 	console.info(url)
@@ -192,6 +209,16 @@ async function file(filing: Filing): Promise<number> {
 	return SUCCESS_EXIT_CODE
 }
 
+async function file(filing: Filing): Promise<number> {
+	if (!is_admitted(filing)) return FAILURE_EXIT_CODE
+	const labels = await labels_of(filing)
+
+	if (labels === undefined) return FAILURE_EXIT_CODE
+	if (!(await is_wip_clear(filing)) || !(await is_scout_clear(filing))) return FAILURE_EXIT_CODE
+
+	return await send(filing, labels)
+}
+
 async function filing_of(args: FileArguments): Promise<Filing | string> {
 	const body = await read_body(args.body_file)
 
@@ -228,7 +255,7 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 	process.exitCode = await run(argv)
 }
 
-const issue_file_cli = { THIRD_PARTY_MESSAGE, run }
+const issue_file_cli = { FRESH_ISSUE_POLL, THIRD_PARTY_MESSAGE, run }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
 

package/scripts/issue/issue-file.ts

@@ -1,5 +1,6 @@
 import type { parseArgs } from 'node:util'
 import { epic_issue } from '#scripts/epic/epic-issue'
+import { epic_triage } from '#scripts/epic/epic-triage'
 import { github_issue_url } from '#scripts/gh/github-issue-url'
 import { cli_flags } from '#scripts/lib/cli-flags'
 import { issue_backlinks } from './issue-backlinks'
@@ -9,6 +10,8 @@ import {
 	DEPTH_LABEL_ORDER,
 	FILING_ROUTE_LABELS,
 	has_label_name,
+	RUN_LANE_LABEL,
+	RUN_SOLO_LABEL,
 } from './issue-labels'
 import { markdown_section } from './markdown-section'
 
@@ -152,6 +155,19 @@ function labels_of(args: FileArguments, body: string, is_auto_ok = false): Reado
 	return [...labels, AUTO_OK_LABEL]
 }
 
+// Why an `auto-ok` filing with neither `run:lane` nor `run:solo` is refused, or `undefined` when it is
+// not (joshuafolkken/kit#3313). The offer paths withhold every candidate while one opted-in Issue is
+// untriaged, so a run's own filing without the judgement stopped every lane. No default is applied:
+// `run:solo` is the answer that keeps a verification defect from running beside others, and only a
+// reading of the Issue gives it (`backlogrun-lanes.md`).
+function triage_problem(labels: ReadonlyArray<string>): string | undefined {
+	const is_owed = has_label_name(labels, AUTO_OK_LABEL) && !epic_triage.has_triage_label(labels)
+
+	if (!is_owed) return undefined
+
+	return `an \`${AUTO_OK_LABEL}\` filing needs \`--label ${RUN_LANE_LABEL}\` or \`--label ${RUN_SOLO_LABEL}\` — \`${RUN_SOLO_LABEL}\` only for a defect in kit's own verification that makes unrelated PRs answer wrongly on main now (\`backlogrun-lanes.md\`), else \`${RUN_LANE_LABEL}\``
+}
+
 function is_same_repository(target: string, current: string): boolean {
 	return target.toLowerCase() === current.toLowerCase()
 }
@@ -202,7 +218,14 @@ function unacknowledged(
 	return candidates.filter((candidate) => !distinct.includes(candidate))
 }
 
-const issue_file = { parse, labels_of, origin_problem, unacknowledged, is_same_repository }
+const issue_file = {
+	parse,
+	labels_of,
+	origin_problem,
+	triage_problem,
+	unacknowledged,
+	is_same_repository,
+}
 
 export type { FileArguments }
 export { issue_file }

package/scripts/issue/issue-scout-closed.ts

@@ -1,7 +1,7 @@
 import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { issue_label_schema } from '#scripts/git/git-schemas'
 import { PAGE_CEILING_CAUSE } from '#scripts/git/listing-cutoff'
 import { parse_json_array_or_undefined } from '#scripts/git/parse-json-array'
-import { issue_label_schema } from '#scripts/git/schemas'
 import { z } from 'zod'
 import { EPIC_LABEL, has_any_label } from './issue-labels'
 import type { ScoutIssue } from './issue-scout'

package/scripts/issue/issue-state-cli.ts

@@ -2,6 +2,7 @@
 import { fileURLToPath } from 'node:url'
 import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { bounded_pool } from '#scripts/lib/bounded-pool'
+import { cli_flags } from '#scripts/lib/cli-flags'
 import { issue_report_failures, type ReadFailureKind } from './issue-report-failures'
 import { issue_state, type IssueState } from './issue-state'
 
@@ -28,9 +29,6 @@ import { issue_state, type IssueState } from './issue-state'
 
 const FAILURE_EXIT_CODE = 1
 const ARGV_OFFSET = 2
-const REPO_FLAG = '--repo'
-const FLAG_PREFIX = '-'
-const INLINE_REPO_FLAG = `${REPO_FLAG}=`
 const ISSUE_NUMBER_PATTERN = /^[1-9]\d*$/u
 const USAGE = 'Usage: josh issue:state <issue-number> [<issue-number> ...] [--repo <owner/repo>]'
 // A blank line between the blocks of a multi-number report, so a person sees where one issue ends
@@ -60,85 +58,43 @@ interface IssueReport {
 	result: StateRead
 }
 
-// `absent` and "given but with nothing usable after it" are different answers. Falling back to the
-// session's repository on the second would print a confident state for a *different* issue of the
-// same number, which is the exact misread the `--repo` argument exists to prevent.
-//
-// A named flag carries the argv positions it actually occupied, never the token text it matched
-// (joshuafolkken/kit#1355). Removing tokens by value removes every token that happens to look like
-// one of them — a second `--repo`, a repeated `owner/repo` — and a token removed is a token nobody
-// is told about, which is the whole failure this file refuses elsewhere.
-type RepoFlag =
-	| { kind: 'absent' }
-	| { kind: 'named'; repo: string; consumed: ReadonlyArray<number> }
-	| { kind: 'incomplete' }
-
-// Both spellings gh itself accepts. `--repo=owner/repo` falling through to the separate-word branch
-// would read as no repository at all, which is the fall back to the session's repository above.
-function read_inline_repo(argv: ReadonlyArray<string>): RepoFlag | undefined {
-	const inline = argv.find((argument) => argument.startsWith(INLINE_REPO_FLAG))
-
-	if (inline === undefined) return undefined
-
-	const repo = inline.slice(INLINE_REPO_FLAG.length)
-
-	if (repo.length === 0) return { kind: 'incomplete' }
-
-	return { kind: 'named', repo, consumed: [argv.indexOf(inline)] }
+// The read goes through `cli_flags`, both spellings gh itself accepts included (`--repo owner/repo`,
+// `--repo=owner/repo`), and is strict (joshuafolkken/kit#3261). An unrecognized flag refuses the
+// call: `--rep=owner/repo` used to be discarded for starting with a dash, so the call fell back to
+// the session's repository and printed a confident state for a *different* repository's issue of
+// that number (joshuafolkken/kit#1355).
+const OPTIONS = { repo: { type: 'string', multiple: true } } as const
+
+// `absent` and "given but with nothing usable" are different answers. Falling back to the session's
+// repository on the second — an empty value, or `--repo` given twice — would print a confident state
+// for a *different* issue of the same number, which is the exact misread `--repo` exists to prevent.
+function read_repo(given: ReadonlyArray<string> | undefined): { repo?: string } | undefined {
+	if (given === undefined) return {}
+	const [repo, ...rest] = given
+
+	return repo !== undefined && rest.length === 0 && repo.length > 0 ? { repo } : undefined
 }
 
-function read_separate_repo(argv: ReadonlyArray<string>): RepoFlag {
-	const index = argv.indexOf(REPO_FLAG)
-
-	if (index === -1) return { kind: 'absent' }
-
-	const value_index = index + 1
-	const repo = argv[value_index]
-
-	if (repo === undefined || repo.startsWith(FLAG_PREFIX)) return { kind: 'incomplete' }
-
-	return { kind: 'named', repo, consumed: [index, value_index] }
-}
-
-function read_repo_flag(argv: ReadonlyArray<string>): RepoFlag {
-	return read_inline_repo(argv) ?? read_separate_repo(argv)
-}
-
-// The argv positions the repository flag occupied, and nothing else. Everything outside this set was
-// offered as an issue number, whatever it looks like — so a flag nobody recognizes reaches the check
-// below and refuses the call instead of vanishing from it (joshuafolkken/kit#1355).
-function consumed_indices(repo_flag: RepoFlag): ReadonlySet<number> {
-	return new Set(repo_flag.kind === 'named' ? repo_flag.consumed : [])
+// A token that is not a number refuses the whole invocation rather than being dropped. Dropping it
+// answers fewer numbers than were asked for and still exits zero — and with one number left, the
+// surviving block prints in the single-number shape, so nothing in the output says a number went
+// unanswered. `#1262` copied out of a `diag` table is exactly that token.
+function is_issue_numbers(positionals: ReadonlyArray<string>): boolean {
+	return (
+		positionals.length > 0 && positionals.every((argument) => ISSUE_NUMBER_PATTERN.test(argument))
+	)
 }
 
 function parse_request(argv: ReadonlyArray<string>): StateRequest | undefined {
-	const repo_flag = read_repo_flag(argv)
-
-	if (repo_flag.kind === 'incomplete') return undefined
-
-	// The repository is read first, flag word and value together, so neither is ever mistaken for an
-	// issue number — and nothing else is removed here. Every remaining token is one the caller offered
-	// as an issue number, whatever it looks like.
-	const consumed = consumed_indices(repo_flag)
-	const rest = argv.filter((_argument, index) => !consumed.has(index))
-	const numbers = rest.filter((argument) => ISSUE_NUMBER_PATTERN.test(argument))
-
-	// A token that is not a number refuses the whole invocation rather than being dropped. Dropping
-	// it answers fewer numbers than were asked for and still exits zero — and with one number left,
-	// the surviving block prints in the single-number shape, so nothing in the output says a number
-	// went unanswered. `#1262` copied out of a `diag` table is exactly that token.
-	//
-	// An unrecognized flag reaches this same check rather than a lenient one of its own
-	// (joshuafolkken/kit#1355). `--rep=owner/repo` used to be discarded for starting with a dash, so
-	// the call fell back to the session's repository and printed a confident state for a *different*
-	// repository's issue of that number — the misread `incomplete` already exists to prevent.
-	if (numbers.length === 0 || numbers.length !== rest.length) return undefined
+	const parsed = cli_flags.arguments_of(argv, OPTIONS)
+	if (parsed === undefined) return undefined
+	const repo = read_repo(parsed.values.repo)
+
+	if (repo === undefined || !is_issue_numbers(parsed.positionals)) return undefined
 
 	// In the order they were typed, with a repeat dropped: repeating a number would spend a second
 	// read on an answer already in hand, and print a second block a caller counting rows counts twice.
-	const issue_numbers = [...new Set(numbers)]
-
-	return repo_flag.kind === 'named' ? { issue_numbers, repo: repo_flag.repo } : { issue_numbers }
+	return { issue_numbers: [...new Set(parsed.positionals)], ...repo }
 }
 
 // One number's read, reduced to what the report needs and nothing printed yet. Separating the two

package/scripts/josh/josh-command-map.ts

@@ -78,6 +78,8 @@ const ALIASES: Record<string, string> = {
 	rvf: 'review:findings',
 	ruv: 'rule:value',
 	ev: 'eval',
+	lsm: 'lane:sample',
+	lst: 'lane:stats',
 }
 
 // The canonical name of a `josh` subcommand: an alias expands, and anything else passes through

package/scripts/josh/josh-command-types.ts

@@ -60,6 +60,17 @@ interface CommandEntry {
 	// listing carries only what a consumer can run (joshuafolkken/kit#1988). The audience in
 	// `reference` separately decides whether the command appears in the default listing.
 	is_kit_only?: boolean
+	// Pre-built to `dist/commands/` so a consumer's `dist/josh.js` imports it in its own process
+	// instead of spawning tsx for it (joshuafolkken/kit#3328, `docs/maintainers/runtime-bundling.md`).
+	is_bundled?: boolean
+	// The cores the command reserves from the machine-wide budget before it starts its heavy tools
+	// (joshuafolkken/kit#3345). `josh-logic.ts` claims them at the one dispatch point every command
+	// passes through, so the command only declares the number. A function means the weight is read
+	// when the command starts: the unit suite's share depends on what else is running at that moment.
+	// **The edit hook declares none, on purpose.** It formats one file per edit and finishes in well
+	// under a second, so a wait for room on the machine would stall every edit for the length of
+	// another lane's check.
+	core_weight?: number | (() => number)
 }
 
 // The name `josh gate` registers under. It lives here rather than in `verification-gate.ts` so a

package/scripts/josh/josh-commands-ai.ts

@@ -143,14 +143,14 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 		reference: ['[<owner/repo>]', 'automation', ['none']],
 	},
 	'run:merge': {
-		script: 'scripts/run/run-merge-cli.ts',
+		script: 'scripts/run/merge/run-merge-cli.ts',
 		description:
 			'Collapse a backlogrun merge event into one call: confirm the child, do the post-merge steps, offer the next child',
 		category: 'AI tools',
 		reference: [ISSUE_WITH_OPTIONS, 'automation', ['git', 'network']],
 	},
 	'run:review': {
-		script: 'scripts/run/run-review-cli.ts',
+		script: 'scripts/run/review/run-review-cli.ts',
 		description:
 			'Start the gate in the background and print the /code-review brief in one call so the two overlap (--join to join the gate and check its verdict)',
 		category: 'AI tools',
@@ -171,7 +171,7 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 	// (`run:tail`) were four round trips re-billing the run's full context each. It stops at the first
 	// failed step and names it, so the run reads only the step to fix.
 	ship: {
-		script: 'scripts/run/run-ship-cli.ts',
+		script: 'scripts/run/ship/run-ship-cli.ts',
 		description:
 			'Ship a change in one call: gate, commit/push/PR, the CI-wait merge and the report bookkeeping, stopping at the first failed step',
 		category: 'AI tools',
@@ -182,7 +182,7 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 		],
 	},
 	'run:event': {
-		script: 'scripts/run/run-event-cli.ts',
+		script: 'scripts/run/event/run-event-cli.ts',
 		description:
 			'Append to, read or watch the run’s append-only event stream (--append <kind> <text> | --from|--follow <n> | --watch [<n>] | --last)',
 		category: 'AI tools',

package/scripts/josh/josh-commands-backlog.ts

@@ -1,4 +1,4 @@
-import type { CommandEntry } from './josh-command-types'
+import { OPTIONAL_ENV_FILE_FLAGS, type CommandEntry } from './josh-command-types'
 
 // The `backlog:*` command registry, split out of `josh-commands-ai.ts` so that file stays under its
 // 300-code-line limit, exactly as `LANE_COMMANDS` and `SPLIT_COMMANDS` were for the same reason
@@ -41,6 +41,9 @@ const BACKLOG_COMMANDS: Record<string, CommandEntry> = {
 	},
 	'backlog:stalled': {
 		script: 'scripts/backlog/backlog-stalled-cli.ts',
+		// A stall sends one Telegram warning (joshuafolkken/kit#3357). The `Stop` hook calls the detector
+		// directly, so this flag costs only the manual command its in-process dispatch.
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
 		description:
 			'Report whether ready backlog work is sitting undispatched with a free lane and no recent dispatch',
 		category: 'AI tools',

package/scripts/josh/josh-commands-development.ts

@@ -1,3 +1,5 @@
+import { core_budget } from '#scripts/gate/core-budget'
+import { gate_plan } from '#scripts/gate/gate-plan'
 import { GATE_COMMAND, type CommandEntry } from './josh-command-types'
 
 const FILE_ARGUMENTS = '[files...]'
@@ -25,18 +27,21 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		description: 'Check code with prettier and eslint (skips a tool a basic project lacks)',
 		category: 'Development',
 		reference: ['', 'developer', ['processes']],
+		core_weight: core_budget.CORE_WEIGHTS.lint,
 	},
 	'lint:related': {
 		script: 'scripts/lint/lint-related.ts',
 		description: 'Check only the changed files with prettier and eslint (whole tree on fallback)',
 		category: 'Development',
 		reference: [FILE_ARGUMENTS, 'developer', ['processes']],
+		core_weight: core_budget.CORE_WEIGHTS.lint,
 	},
 	lines: {
 		script: 'scripts/lines/lines-command.ts',
 		description: "Print a file's code lines against the max-lines limit and the headroom left",
 		category: 'Development',
 		reference: [REQUIRED_FILE_ARGUMENTS, 'developer', ['none']],
+		core_weight: core_budget.CORE_WEIGHTS.eslint_scan,
 	},
 	'refactor:scan': {
 		script: 'scripts/refactor/refactor-scan-cli.ts',
@@ -44,6 +49,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 			'List refactoring candidates in the changed scope by category and answer clear/candidates',
 		category: 'Development',
 		reference: ['', 'automation', ['processes']],
+		core_weight: core_budget.CORE_WEIGHTS.eslint_scan,
 	},
 	bytes: {
 		script: 'scripts/lines/bytes-command.ts',
@@ -130,6 +136,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		description: 'Run spell check including dotfiles',
 		category: 'Development',
 		reference: ['', 'developer', ['processes']],
+		core_weight: core_budget.CORE_WEIGHTS.spell_check,
 	},
 	behavior: {
 		script: 'scripts/behavior/behavior-cli.ts',
@@ -151,12 +158,14 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 			'Run unit tests with Vitest (skips when Vitest is absent; fails when it has no tests)',
 		category: 'Development',
 		reference: [FILTER_ARGUMENTS, 'developer', ['processes']],
+		core_weight: gate_plan.direct_unit_weight,
 	},
 	'test:related': {
 		script: 'scripts/test/test-related.ts',
 		description: 'Run only the unit tests related to the changed files (full suite on fallback)',
 		category: 'Development',
 		reference: [FILE_ARGUMENTS, 'developer', ['processes']],
+		core_weight: gate_plan.direct_unit_weight,
 	},
 	'test:declared': {
 		script: 'scripts/test/test-declared.ts',
@@ -203,6 +212,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		description: 'Type-check with tsc (skips a basic project with no TypeScript to check)',
 		category: 'Development',
 		reference: ['[arguments...]', 'developer', ['processes']],
+		core_weight: core_budget.CORE_WEIGHTS.type_check,
 	},
 	port: {
 		script: 'scripts/ports/port-command.ts',

package/scripts/josh/josh-commands-document.ts

@@ -13,6 +13,7 @@ const DOCUMENT_COMMANDS: Record<string, CommandEntry> = {
 		description: 'Print one section of a markdown document, for a `file.md` → "Heading" reference',
 		category: 'AI tools',
 		reference: ['<file> <heading>', 'automation', ['none']],
+		is_bundled: true,
 	},
 	'read:set': {
 		script: 'scripts/document/read-set-cli.ts',

package/scripts/josh/josh-commands-lane.ts

@@ -9,6 +9,10 @@ const LANE_SCRIPT = 'scripts/lane/lane-cli.ts'
 // has to read `.env` to see them — without this the two are documented and unreachable.
 const LANE_ARGUMENTS = { script: LANE_SCRIPT, tsx_arguments: OPTIONAL_ENV_FILE_FLAGS } as const
 const ISSUE_WITH_OPTIONS = '<issue> [options]'
+const MEASURE_ARGUMENTS = {
+	script: 'scripts/lane/lane-measure-cli.ts',
+	tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+} as const
 
 /* eslint-disable @typescript-eslint/naming-convention */
 const LANE_COMMANDS: Record<string, CommandEntry> = {
@@ -69,6 +73,24 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 		category: 'AI tools',
 		reference: ['<issue> [--stash <message>]', 'automation', ['files', 'git', 'processes']],
 	},
+	// The lane-limit measurement (joshuafolkken/kit#3355): `.env` is read so `lane:stats` labels the row
+	// with the `JOSH_LANE_LIMIT` a person set there.
+	'lane:sample': {
+		...MEASURE_ARGUMENTS,
+		description:
+			'Record the machine load (load average, swap, free memory, working lanes) to the lane ledger',
+		category: 'AI tools',
+		reference: ['[--every <seconds>]', 'maintainer', ['files']],
+		default_script_arguments: ['sample'],
+	},
+	'lane:stats': {
+		...MEASURE_ARGUMENTS,
+		description:
+			'Print one table row of lane throughput, gate duration and machine load over a period',
+		category: 'AI tools',
+		reference: ['--period <days> [--limit <lane-limit>]', 'maintainer', ['none']],
+		default_script_arguments: ['stats'],
+	},
 }
 /* eslint-enable @typescript-eslint/naming-convention */
 

package/scripts/josh/josh-commands-maintenance.ts

@@ -21,7 +21,7 @@ const MAINTENANCE_COMMANDS: Record<string, CommandEntry> = {
 		script: 'scripts/overrides/overrides-check.ts',
 		description: 'Check pnpm overrides for drift',
 		category: 'Maintenance',
-		reference: ['[--save]', 'maintainer', ['files']],
+		reference: ['[--save]', 'developer', ['files']],
 	},
 	audit: {
 		script: 'scripts/security/security-audit.ts',
@@ -49,7 +49,7 @@ const MAINTENANCE_COMMANDS: Record<string, CommandEntry> = {
 		],
 		description: 'Update pnpm, dependencies, and run security audit',
 		category: 'Maintenance',
-		reference: ['', 'maintainer', ['files', 'network', 'processes']],
+		reference: ['', 'developer', ['files', 'network', 'processes']],
 		argument_targets: ['latest:corepack', 'latest:update', 'audit'],
 	},
 	'latest:scope': {
@@ -73,13 +73,13 @@ const MAINTENANCE_COMMANDS: Record<string, CommandEntry> = {
 		script: 'scripts/version/latest-corepack.ts',
 		description: 'Update pnpm on the current major while preserving the integrity pin',
 		category: 'Maintenance',
-		reference: ['', 'maintainer', ['files', 'network']],
+		reference: ['', 'developer', ['files', 'network']],
 	},
 	'latest:update': {
 		script: 'scripts/version/latest-update.ts',
 		description: 'Update all dependencies to latest',
 		category: 'Maintenance',
-		reference: ['', 'maintainer', ['files', 'network']],
+		reference: ['', 'developer', ['files', 'network']],
 	},
 }
 /* eslint-enable @typescript-eslint/naming-convention */

package/scripts/josh/josh-commands-run.ts

@@ -6,7 +6,7 @@ import { OPTIONAL_ENV_FILE_FLAGS, type CommandEntry } from './josh-command-types
 // the generated catalog keeps their order.
 
 // One script answers both `run:hold` and `run:release`; the flag below is what tells them apart.
-const RUN_HOLD_SCRIPT = 'scripts/run/run-hold-cli.ts'
+const RUN_HOLD_SCRIPT = 'scripts/run/hold/run-hold-cli.ts'
 
 /* eslint-disable @typescript-eslint/naming-convention */
 const RUN_COMMANDS: Record<string, CommandEntry> = {
@@ -24,19 +24,22 @@ const RUN_COMMANDS: Record<string, CommandEntry> = {
 		default_script_arguments: ['--release'],
 	},
 	'run:tidy': {
-		script: 'scripts/run/run-tidy-cli.ts',
+		script: 'scripts/run/tidy/run-tidy-cli.ts',
 		description: 'Close merged lanes and drop stashes whose issues are all merged',
 		category: 'AI tools',
 		reference: ['', 'automation', ['git', 'network', 'files']],
 	},
 	'run:carry': {
-		script: 'scripts/run/run-carry-cli.ts',
+		script: 'scripts/run/carry/run-carry-cli.ts',
+		// `--stopped` sends the stop confirmation, so the Telegram credentials come from `.env` as for
+		// `run:wake` below (joshuafolkken/kit#3357).
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
 		description: 'Carry one invocation’s budget across its own session cuts',
 		category: 'AI tools',
 		reference: ['<operation> [arguments...]', 'automation', ['files']],
 	},
 	'run:wake': {
-		script: 'scripts/run/run-wake-cli.ts',
+		script: 'scripts/run/wake/run-wake-cli.ts',
 		// `.env` rather than the ambient environment:
 		// the failure warning needs the Telegram credentials, the same
 		// reasons `notify` and `followup` carry these flags.
@@ -46,7 +49,7 @@ const RUN_COMMANDS: Record<string, CommandEntry> = {
 		reference: ['[options]', 'automation', ['processes', 'notifications']],
 	},
 	'run:cut': {
-		script: 'scripts/run/run-cut-cli.ts',
+		script: 'scripts/run/cut/run-cut-cli.ts',
 		description: 'Cut a lane child before the gate and resume a fresh process',
 		category: 'AI tools',
 		reference: ['[--resume] <issue> [--impl] [--handoff <path>]', 'automation', ['files']],
@@ -64,7 +67,7 @@ const RUN_COMMANDS: Record<string, CommandEntry> = {
 		reference: ['<issue> --output <path> [--repo <owner/repo>]', 'automation', ['network']],
 	},
 	'run:progress': {
-		script: 'scripts/run/run-progress-cli.ts',
+		script: 'scripts/run/progress/run-progress-cli.ts',
 		description: 'Report an unattended run’s progress once it has gone quiet for an interval',
 		category: 'AI tools',
 		reference: [
@@ -83,7 +86,9 @@ const RUN_COMMANDS: Record<string, CommandEntry> = {
 	// read the budget, gather the issue reads and decide the pre-implementation step. `run:hold`,
 	// `cost --cut`, `run:prep` and `run:step` were four round trips re-billing a lane's full context each.
 	'run:entry': {
-		script: 'scripts/run/run-entry-cli.ts',
+		script: 'scripts/run/entry/run-entry-cli.ts',
+		// A `busy` hold or an `over` budget sends the stop confirmation (joshuafolkken/kit#3357).
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
 		description:
 			'Open a run in one call: claim the tree, read the budget, bundle the reads, decide the pre-implementation step',
 		category: 'AI tools',