@joshuafolkken/kit 1.1178.0 → 1.1240.0

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

@@ -60,6 +60,20 @@ 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 memory the command's tools hold, claimed with its cores (joshuafolkken/kit#3371); read like
+	// `core_weight`, and none declared is none waited for.
+	memory_mb?: 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,24 @@ 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,
+		memory_mb: core_budget.MEMORY_MB.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,
+		memory_mb: core_budget.MEMORY_MB.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,
+		memory_mb: core_budget.MEMORY_MB.eslint_scan,
 	},
 	'refactor:scan': {
 		script: 'scripts/refactor/refactor-scan-cli.ts',
@@ -44,6 +52,8 @@ 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,
+		memory_mb: core_budget.MEMORY_MB.eslint_scan,
 	},
 	bytes: {
 		script: 'scripts/lines/bytes-command.ts',
@@ -130,6 +140,8 @@ 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,
+		memory_mb: core_budget.MEMORY_MB.spell_check,
 	},
 	behavior: {
 		script: 'scripts/behavior/behavior-cli.ts',
@@ -151,12 +163,16 @@ 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,
+		memory_mb: gate_plan.direct_unit_memory,
 	},
 	'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,
+		memory_mb: gate_plan.direct_unit_memory,
 	},
 	'test:declared': {
 		script: 'scripts/test/test-declared.ts',
@@ -203,6 +219,8 @@ 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,
+		memory_mb: core_budget.MEMORY_MB.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-issue.ts

@@ -69,11 +69,18 @@ const ISSUE_COMMANDS: Record<string, CommandEntry> = {
 			'File an Issue with every filing step: lint, Origin, WIP cap, duplicate scout, labels, then epic:bundle',
 		category: 'AI tools',
 		reference: [
-			'<title> --body-file <path> --depth <0|1|2> [--route <route>] [--label <name>] [--repo <owner/repo>] [--distinct <N,…>] [--over-cap] [--no-auto-ok]',
+			'<title> --body-file <path> --depth <0|1|2> [--route <route>] [--label <name>] [--repo <owner/repo>] [--distinct <N,…>] [--over-cap] [--no-auto-ok] [--release]',
 			'automation',
 			['network'],
 		],
 	},
+	'issue:release': {
+		script: 'scripts/issue/issue-release-cli.ts',
+		description:
+			"Link an Issue to the repository's open release Issue as its blocker, filing one when none is open",
+		category: 'AI tools',
+		reference: ['<issue>', 'automation', ['network']],
+	},
 }
 /* eslint-enable @typescript-eslint/naming-convention */
 

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> = {
@@ -35,7 +39,8 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 	},
 	'lane:prune': {
 		...LANE_ARGUMENTS,
-		description: 'Close every lane an interruption left without its work tree',
+		description:
+			'Close every lane an interruption left without its work tree, then sweep unregistered leftovers under the lanes root',
 		category: 'AI tools',
 		reference: ['', 'automation', ['files', 'git']],
 		default_script_arguments: ['prune'],
@@ -69,6 +74,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',
@@ -45,11 +45,11 @@ const MAINTENANCE_COMMANDS: Record<string, CommandEntry> = {
 		shell: [
 			'sh',
 			'-c',
-			'export NODE_AUTH_TOKEN=$(gh auth token) && pnpm josh latest:guard && pnpm josh latest:corepack && pnpm josh latest:update && pnpm josh ranges && pnpm josh audit && pnpm josh latest:scope --record',
+			'export NODE_AUTH_TOKEN=$(gh auth token) && pnpm josh latest:guard && pnpm josh latest:update && pnpm josh ranges && pnpm josh audit && pnpm josh latest:corepack && pnpm josh latest:scope --record',
 		],
-		description: 'Update pnpm, dependencies, and run security audit',
+		description: 'Update dependencies, run security audit, then update pnpm',
 		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',

package/scripts/josh/josh-in-process.ts

@@ -1,4 +1,5 @@
 import { realpathSync } from 'node:fs'
+import path from 'node:path'
 import { pathToFileURL } from 'node:url'
 import type { CommandEntry } from './josh-command-types'
 
@@ -8,26 +9,44 @@ import type { CommandEntry } from './josh-command-types'
 // (joshuafolkken/kit#1342). The script is ordinary TypeScript and a TypeScript loader is already
 // installed by the time this file runs, so the dispatcher evaluates the script itself instead.
 const TYPESCRIPT_EXTENSION = '.ts'
+const JAVASCRIPT_EXTENSION = '.js'
+const BUNDLED_COMMAND_DIRECTORY = path.join('dist', 'commands')
 const FAILURE_EXIT_CODE = 1
 
 // The dispatcher may only load a `.ts` script in its own process when it was itself loaded as
 // TypeScript — which is exactly the condition under which a loader capable of it is present. A
-// consumer runs the bundled `dist/josh.js` under plain node, whose `import.meta.url` ends in `.js`,
-// so that install keeps the spawning path unchanged rather than failing on a module node cannot
-// load at all.
+// consumer runs the bundled `dist/josh.js` under plain node, whose `import.meta.url` ends in `.js`.
 function is_typescript_dispatcher(dispatcher_url: string): boolean {
 	return dispatcher_url.endsWith(TYPESCRIPT_EXTENSION)
 }
 
+// A command marked `is_bundled` is pre-built to `dist/commands/<script basename>.js` by
+// `scripts/build/build-commands.ts` (joshuafolkken/kit#3328). The path is derived here, in a module
+// the dispatcher bundle already carries, so the build and the dispatcher cannot name two locations.
+function bundled_script_path(package_directory: string, script: string): string {
+	const name = `${path.basename(script, TYPESCRIPT_EXTENSION)}${JAVASCRIPT_EXTENSION}`
+
+	return path.join(package_directory, BUNDLED_COMMAND_DIRECTORY, name)
+}
+
+// The file this dispatcher imports in its own process, or `undefined` to spawn tsx instead.
 // `tsx_arguments` are node flags the script needs *before* its own code runs — today every one of
 // them a form of `--env-file`, which has no in-process equivalent that reproduces node's own
 // parsing and precedence. Those commands (`doctor`, `latest:scope`, `followup`, `notify`) keep a
 // process of their own; each runs at most a few times per run, so none of them is where the cost
-// this saves accumulates.
-function can_run_in_process(entry: CommandEntry, dispatcher_url: string): boolean {
-	if (entry.script === undefined || entry.tsx_arguments !== undefined) return false
+// this saves accumulates. Under plain node, which cannot load a `.ts` script at all, only a
+// pre-built command runs in-process; every other one keeps spawning tsx.
+function in_process_target(
+	entry: CommandEntry,
+	package_directory: string,
+	dispatcher_url: string,
+): string | undefined {
+	if (entry.script === undefined || entry.tsx_arguments !== undefined) return undefined
+	if (is_typescript_dispatcher(dispatcher_url)) return path.join(package_directory, entry.script)
 
-	return is_typescript_dispatcher(dispatcher_url)
+	return entry.is_bundled === true
+		? bundled_script_path(package_directory, entry.script)
+		: undefined
 }
 
 // `process.exitCode` is typed `number | string | undefined`. Only the numeric form is an exit code
@@ -75,6 +94,6 @@ async function run_in_process(
 	return read_exit_code()
 }
 
-const josh_in_process = { can_run_in_process, run_in_process }
+const josh_in_process = { bundled_script_path, in_process_target, run_in_process }
 
-export { FAILURE_EXIT_CODE, josh_in_process }
+export { BUNDLED_COMMAND_DIRECTORY, FAILURE_EXIT_CODE, josh_in_process }

package/scripts/josh/josh-logic.ts

@@ -2,6 +2,8 @@ import { existsSync, readFileSync } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { resolve_local_bin, resolve_package_bin } from '#scripts/build/local-bin'
+import { core_budget } from '#scripts/gate/core-budget'
+import { ancestor_directories } from '#scripts/lib/ancestor-directories'
 import { package_version_schema } from '#scripts/lib/schemas'
 import { resolve_spawn_exit } from '#scripts/lib/spawn-exit'
 import { execaSync } from 'execa'
@@ -37,15 +39,11 @@ interface TsxRunner {
 // from the bundled dist/josh.js (one level under the root) and from the tsx source at
 // scripts/josh/ (two levels), so this file's depth no longer has to be hard-coded.
 function find_package_directory(start_directory: string): string {
-	let current = start_directory
-
-	while (!existsSync(path.join(current, PACKAGE_JSON))) {
-		const parent = path.dirname(current)
-		if (parent === current) return start_directory
-		current = parent
-	}
-
-	return current
+	return (
+		ancestor_directories.nearest(start_directory, (directory) =>
+			existsSync(path.join(directory, PACKAGE_JSON)),
+		) ?? start_directory
+	)
 }
 
 const PACKAGE_DIR = find_package_directory(path.dirname(fileURLToPath(import.meta.url)))
@@ -226,14 +224,12 @@ async function run_script_entry(
 	entry: CommandEntry,
 	subcommand_arguments: Array<string>,
 ): Promise<number> {
-	const script_path = path.join(PACKAGE_DIR, entry.script ?? '')
 	const script_arguments = [...(entry.default_script_arguments ?? []), ...subcommand_arguments]
+	const target = josh_in_process.in_process_target(entry, PACKAGE_DIR, import.meta.url)
 
-	if (josh_in_process.can_run_in_process(entry, import.meta.url)) {
-		return await josh_in_process.run_in_process(script_path, script_arguments)
-	}
+	if (target !== undefined) return await josh_in_process.run_in_process(target, script_arguments)
 
-	return spawn_script_entry(entry, script_path, script_arguments)
+	return spawn_script_entry(entry, path.join(PACKAGE_DIR, entry.script ?? ''), script_arguments)
 }
 
 function github_prerequisite_exit(resolved: string, is_consumer: boolean): number | undefined {
@@ -274,7 +270,7 @@ function pre_dispatch_exit(
 	return USAGE_ERROR_EXIT_CODE
 }
 
-async function dispatch_entry(
+async function run_entry(
 	entry: CommandEntry,
 	subcommand_arguments: Array<string>,
 ): Promise<number> {
@@ -283,6 +279,29 @@ async function dispatch_entry(
 	return await run_script_entry(entry, subcommand_arguments)
 }
 
+function declared(value: number | (() => number) | undefined): number | undefined {
+	return typeof value === 'function' ? value() : value
+}
+
+// **Every command passes through here, so this is where a declared weight is reserved**
+// (joshuafolkken/kit#3345). A heavy command run directly, outside `josh gate`, used to start its tools
+// without claiming a place. A command under a parent that already holds its cores claims nothing:
+// `core_budget.with_command_reservation` reads the mark that parent set.
+async function dispatch_entry(
+	entry: CommandEntry,
+	subcommand_arguments: Array<string>,
+): Promise<number> {
+	const weight = declared(entry.core_weight)
+
+	if (weight === undefined) return await run_entry(entry, subcommand_arguments)
+
+	return await core_budget.with_command_reservation(
+		weight,
+		async () => await run_entry(entry, subcommand_arguments),
+		{ memory_mb: declared(entry.memory_mb) },
+	)
+}
+
 async function run_command(
 	cmd: string,
 	subcommand_arguments: Array<string>,

package/scripts/josh/process-identity.ts

@@ -3,6 +3,7 @@ import { randomUUID } from 'node:crypto'
 import { readFileSync, rmSync } from 'node:fs'
 import { createServer, type Server } from 'node:net'
 import path from 'node:path'
+import { PROBE_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { PLATFORM_TEMP_ROOT } from './platform-temporary'
 
 // Whether the process a record names is still the one that wrote it (joshuafolkken/kit#1245).
@@ -48,9 +49,6 @@ const PID_FLAG = '-p'
 // runs in** — nothing is inherited, so the token depends on the process being asked about and on
 // nothing whatever about who is asking.
 const PROBE_ENVIRONMENT = { TZ: 'UTC', LC_ALL: 'C' }
-// A probe that hung would hang `josh review:brief`, `josh bench` and the unit suite's worker share
-// alike. Failing is harmless here: it answers "cannot tell", which every caller already handles.
-const PROBE_TIMEOUT_MS = 2000
 // `process.kill(pid, 0)` runs every permission check and delivers nothing, so it is the standard
 // liveness probe: it throws `ESRCH` where the process is gone.
 const LIVENESS_SIGNAL = 0

package/scripts/josh/session-language-cli.ts

@@ -20,16 +20,16 @@ import { session_language, type Resolution } from './session-language'
 
 const { DEFAULT_SESSION_LANG, ENV_KEY, resolve_session_lang } = session_language
 const ENGLISH_OPT_IN_LANG = 'en'
-const SCOPE_NOTE =
-	'write session dialogue, AskUserQuestion labels/descriptions and artifact prose (Issue bodies, comments, Telegram) in this language. English stays only for Issue/PR titles, code comments/test titles/commit messages, and script-fixed strings.'
 
 // The file load happens in `main`, on the command path only; the resolver reads the environment.
+// The line carries the value alone: what the language covers is `CLAUDE.md` → "Output language",
+// already in context every turn, so repeating it here only spent context on each prompt.
 function format_line(resolution: Resolution): string {
 	const suffix = resolution.is_default
 		? ` (default; set ${ENV_KEY}=${ENGLISH_OPT_IN_LANG} for English)`
 		: ''
 
-	return `Session language (${ENV_KEY}): ${resolution.lang}${suffix} — ${SCOPE_NOTE}`
+	return `Session language (${ENV_KEY}): ${resolution.lang}${suffix}`
 }
 
 function main(): void {
@@ -42,7 +42,6 @@ const session_language_cli = {
 	ENV_KEY,
 	format_line,
 	resolve_session_lang,
-	SCOPE_NOTE,
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) main()

package/scripts/lane/lane-await.ts

@@ -1,6 +1,7 @@
 import { spawnSync } from 'node:child_process'
 import { setTimeout as sleep } from 'node:timers/promises'
 import { parseArgs } from 'node:util'
+import { PROBE_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { run_liveness } from '#scripts/run/run-liveness'
 import { lane_child_invocation } from './lane-child-invocation'
 import { lane_handoff } from './lane-handoff'
@@ -66,7 +67,10 @@ interface RunConfig extends CheckConfig {
 
 function is_process_running_default(issue: string): boolean {
 	const pattern = lane_child_invocation.process_pattern(issue)
-	const result = spawnSync('pgrep', ['-f', pattern], { encoding: 'utf8' })
+	const result = spawnSync('pgrep', ['-f', pattern], {
+		encoding: 'utf8',
+		timeout: PROBE_TIMEOUT_MS,
+	})
 
 	if (result.status === PROCESS_FOUND) return true
 

package/scripts/lane/lane-child-invocation.ts

@@ -1,6 +1,6 @@
 import { run_issue_number } from '#scripts/run/run-issue-number'
-import { run_ship_next, type ShipResume } from '#scripts/run/run-ship-next'
-import type { Stage } from '#scripts/run/run-ship-stage'
+import { run_ship_next, type ShipResume } from '#scripts/run/ship/run-ship-next'
+import type { Stage } from '#scripts/run/ship/run-ship-stage'
 
 interface ShipStop extends ShipResume {
 	stage: Stage

package/scripts/lane/lane-cli.ts

@@ -2,11 +2,11 @@
 import { fileURLToPath } from 'node:url'
 import { epic_busy } from '#scripts/epic/epic-busy'
 import { git_gh_command } from '#scripts/gh/git-gh-command'
-import type { OpenIssueData } from '#scripts/git/schemas'
+import type { OpenIssueData } from '#scripts/git/git-schemas'
 import { issue_cite, type IssueCiter } from '#scripts/issue/issue-cite'
 import { error_text } from '#scripts/lib/error-message'
-import { run_carry } from '#scripts/run/run-carry'
-import { run_carry_reclaim } from '#scripts/run/run-carry-reclaim'
+import { run_carry } from '#scripts/run/carry/run-carry'
+import { run_carry_reclaim } from '#scripts/run/carry/run-carry-reclaim'
 import { lane_await } from './lane-await'
 import { lane_close, type CloseOutcome, type SweepOutcome } from './lane-close'
 import { lane_dispatch, type DispatchOutcome } from './lane-dispatch'
@@ -16,6 +16,7 @@ import { lane_output, type ReadOutcome, type RecordOutcome } from './lane-output
 import { lane_registry, type LaneInfo } from './lane-registry'
 import { lane_report } from './lane-report'
 import { lane_seed_policy } from './lane-seed'
+import { lane_stray } from './lane-stray'
 
 // `josh lane:open` / `lane:close` / `lane:list` / `lane:prune` — the lane's whole lifecycle
 // (joshuafolkken/kit#1490).
@@ -268,7 +269,14 @@ async function list_command(rest: ReadonlyArray<string>): Promise<number> {
 async function prune_command(rest: ReadonlyArray<string>): Promise<number> {
 	if (rest.length > 0) return report_usage()
 
-	return report_sweep(await lane_close.prune_lanes())
+	const code = report_sweep(await lane_close.prune_lanes())
+
+	// After the closes, so a lane whose close left its directory behind is swept in the same run. A
+	// kept stray is reported, never a failure: it waits on a person, and a non-zero exit would stop
+	// every `backlogrun` preparation until one came (joshuafolkken/kit#3370).
+	await lane_stray.sweep_and_report()
+
+	return code
 }
 
 // The recorded path goes to standard output on both arms, so