@joshuafolkken/kit 1.1166.0 → 1.1229.0

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,28 @@ async function dispatch_entry(
 	return await run_script_entry(entry, subcommand_arguments)
 }
 
+function command_weight(entry: CommandEntry): number | undefined {
+	return typeof entry.core_weight === 'function' ? entry.core_weight() : entry.core_weight
+}
+
+// **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 = command_weight(entry)
+
+	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),
+	)
+}
+
 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'

package/scripts/lane/lane-dispatch.ts

@@ -1,12 +1,13 @@
 import { agent_argv, type AgentArgv, type AgentArgvResult } from '#scripts/agent/agent-argv'
 import { agent_role_profile, type AgentProfile } from '#scripts/agent/agent-role-profile'
 import { git_gh_command } from '#scripts/gh/git-gh-command'
+import type { LabelWrite } from '#scripts/gh/git-gh-issue-write'
 import { IN_PROGRESS_LABEL } from '#scripts/issue/issue-labels'
 import { telegram_notify } from '#scripts/notify/telegram-notify'
 import { detached_launch } from '#scripts/run/detached-launch'
+import { run_event_stream } from '#scripts/run/event/run-event-stream'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
 import { run_ending } from '#scripts/run/run-ending'
-import { run_event_stream } from '#scripts/run/run-event-stream'
-import { run_event_stream_emit } from '#scripts/run/run-event-stream-emit'
 import { run_issue_number } from '#scripts/run/run-issue-number'
 import { lane_child_invocation } from './lane-child-invocation'
 import { lane_child_marker } from './lane-child-marker'
@@ -79,7 +80,7 @@ type DispatchOutcome =
 	// that marks a child as holding its lane — the lane count, the offer filter, `run:progress` and the
 	// stale check all read it — so a child that ran without it would be counted as an empty lane and
 	// handed to a second session. Refusing the launch keeps "dispatched" and "counted as busy" one state.
-	| { kind: typeof LABEL_UNSET_KIND }
+	| { kind: typeof LABEL_UNSET_KIND; reason: string }
 
 type LogOutcome = { kind: 'ready'; path: string } | { kind: 'unrecordable'; reason: string }
 
@@ -305,9 +306,10 @@ function prepared(lane: LaneInfo): Prepared {
 // to its (idempotent) apply. `issue_add_label` creates the label if the repository lacks it — a
 // `POST /issues/{N}/labels` provisions a missing label with a generated color (measured on
 // joshuafolkken/kit#1026, `git-gh-issue-write.ts`) — so no separate `label_ensure` is needed here, and
-// its `false` is a real refusal to launch rather than a note.
-async function mark_in_progress(issue: string): Promise<boolean> {
-	return await git_gh_command.issue_add_label(issue, IN_PROGRESS_LABEL)
+// its unapplied answer is a real refusal to launch rather than a note — confirmed by a read-back, so
+// a write that landed but answered with an error still launches (joshuafolkken/kit#3312).
+async function mark_in_progress(issue: string): Promise<LabelWrite> {
+	return await git_gh_command.issue_apply_label(issue, IN_PROGRESS_LABEL)
 }
 
 // The dispatch owns both halves of the marker: it applied it, so a launch that never started takes it
@@ -324,8 +326,12 @@ async function unmark_in_progress(issue: string): Promise<void> {
 
 // A started child is recorded on the run's stream, which is where the stall detector ages the last
 // dispatch from (joshuafolkken/kit#2464) — unrecorded, every stall read "hours since the last dispatch"
-// minutes after a launch. A failed start records nothing: no child is running.
+// minutes after a launch. A failed start records nothing: no child is running. The marker is claimed
+// first, so a refused one starts nothing.
 async function finish_dispatch(issue: string, request: StartRequest): Promise<DispatchOutcome> {
+	const mark = await mark_in_progress(issue)
+
+	if (!mark.is_applied) return { kind: LABEL_UNSET_KIND, reason: mark.reason }
 	const outcome = await started(request)
 
 	const is_failed = outcome.kind === 'failed'
@@ -353,8 +359,6 @@ async function dispatch_child(issue: string): Promise<DispatchOutcome> {
 
 	if (log.kind !== 'ready') return log
 
-	if (!(await mark_in_progress(issue))) return { kind: LABEL_UNSET_KIND }
-
 	return await finish_dispatch(issue, { lane, log_path: log.path, ...built })
 }
 
@@ -410,7 +414,7 @@ function describe(outcome: DispatchOutcome, issue: string): string {
 	if (outcome.kind === 'unrecordable') return outcome.reason
 
 	if (outcome.kind === LABEL_UNSET_KIND) {
-		return `The child for #${issue} was not started: the \`${IN_PROGRESS_LABEL}\` label could not be applied, so the lane would be counted as empty. Nothing was launched.`
+		return `The child for #${issue} was not started: the \`${IN_PROGRESS_LABEL}\` label could not be applied (${outcome.reason}), so the lane would be counted as empty. Nothing was launched.`
 	}
 
 	if (outcome.kind === 'failed') {

package/scripts/lane/lane-environment.ts

@@ -185,9 +185,13 @@ function replace_assignment(
 	key: string,
 ): Array<string> {
 	return lines.flatMap((entry, index) => {
+		// One return type across the branches (sonarjs/function-return-type) keeps the array wrappers.
+		// eslint-disable-next-line unicorn/no-unnecessary-array-flat-map -- see above
 		if (index === keep) return [assignment]
+		if (is_key_line(entry, key)) return []
 
-		return is_key_line(entry, key) ? [] : [entry]
+		// eslint-disable-next-line unicorn/no-unnecessary-array-flat-map -- see above
+		return [entry]
 	})
 }
 

package/scripts/lane/lane-handoff.ts

@@ -1,5 +1,5 @@
 import { git_common_directory } from '#scripts/git/git-common-directory'
-import { run_ship_detach } from '#scripts/run/run-ship-detach'
+import { run_ship_detach } from '#scripts/run/ship/run-ship-detach'
 import { lane_child_marker, type MarkerSource } from './lane-child-marker'
 
 // Whether a lane has handed its post-implementation region to the detached ship (joshuafolkken/kit#2962).

package/scripts/lane/lane-install.ts

@@ -1,6 +1,7 @@
 import { existsSync } from 'node:fs'
 import path from 'node:path'
 import { buffered_process } from '#scripts/lib/buffered-process'
+import { INSTALL_TIMEOUT_MS } from '#scripts/lib/timeouts'
 
 // Filling the lane, which is the other half of opening one (joshuafolkken/kit#1554).
 //
@@ -34,12 +35,6 @@ const MANIFEST_FILE_NAME = 'package.json'
 // The lane opens with no dependencies installed, and that is the reported state rather than a
 // failure — there was nothing to install, so nothing failed.
 const NO_MANIFEST_OUTPUT = `No ${MANIFEST_FILE_NAME} in the lane, so the dependency install was skipped.`
-// The 3.5 s above is a warm store; a first run, or one after a dependency change, goes to the
-// network, so that figure is not the bound to write here. Ten minutes covers that fetch and still
-// ends `lane:open` when a registry never answers, rather than holding a parallel run open with
-// nothing printed. It is well under the fan-out's own half hour because this one blocks a command a
-// person is waiting on, not a check suite.
-const INSTALL_TIMEOUT_MS = 600_000
 
 interface InstallResult {
 	is_installed: boolean
@@ -85,10 +80,4 @@ async function install_dependencies(directory: string): Promise<InstallResult> {
 const lane_install = { install_dependencies }
 
 export type { InstallResult }
-export {
-	lane_install,
-	INSTALL_ARGUMENTS,
-	INSTALL_TIMEOUT_MS,
-	MANIFEST_FILE_NAME,
-	NO_MANIFEST_OUTPUT,
-}
+export { lane_install, INSTALL_ARGUMENTS, MANIFEST_FILE_NAME, NO_MANIFEST_OUTPUT }

package/scripts/lane/lane-launch-cli.ts

@@ -1,6 +1,8 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { josh_command } from '#scripts/josh/josh-run'
+import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
+import { lane_vacant } from '#scripts/lane/lane-vacant'
 import { cli_flags } from '#scripts/lib/cli-flags'
 import { INSTALL_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { execa } from 'execa'
@@ -15,6 +17,7 @@ import { execa } from 'execa'
 // and messages are reused rather than cloned — `lane:open`'s cut-session guard and its `full` /
 // `already-open` refusals, `stash:pop`'s message-matched pop, `lane:dispatch`'s in-progress claim and
 // warning. Their explanations stream through to stderr; the child's pid is the one thing on stdout.
+// A lane a park kept is the one `already-open` it steps past — `lane_directory` below.
 
 const ARGV_OFFSET = 2
 const SUCCESS_EXIT_CODE = 0
@@ -86,14 +89,43 @@ type LaunchOutcome = { kind: 'launched'; pid: string } | { kind: 'unopened' } |
 const UNOPENED: LaunchOutcome = { kind: 'unopened' }
 const FAILED: LaunchOutcome = { kind: 'failed' }
 
+async function close_if_vacant(lane: LaneInfo | undefined): Promise<void> {
+	if (lane === undefined || !(await lane_vacant.is_vacant(lane))) return
+
+	await josh_command.josh_run(['lane:close', lane.issue], should_forward_stderr)
+}
+
+// **A lane a park kept open is resumed, not reopened** (joshuafolkken/kit#3228). A child parked before
+// its commit leaves its uncommitted work in its lane, and `lane:open` refuses that lane as
+// `already-open` — so the released child is dispatched into the kept tree instead. **Only a lane a
+// child was already dispatched into counts as kept**: `lane:dispatch` records the child's output in the
+// lane's `.env`, and a lane whose install failed never got that far, so it still goes through
+// `lane:open` and its refusal. So does a stranded lane, whose `.env` is gone with its tree.
+//
+// **A lane no child was dispatched into and that holds nothing is closed and opened afresh**
+// (joshuafolkken/kit#3289) — a run cut between the open and the dispatch leaves one. It is reopened
+// rather than reused because nothing recorded whether its install finished. A lane with work or a live
+// process in it still meets `lane:open`'s refusal.
+async function lane_directory(issue: string): Promise<string | undefined> {
+	const kept = await lane_registry.find_open_lane(issue)
+
+	if (kept?.output !== undefined) return kept.directory
+
+	await close_if_vacant(kept)
+
+	const opened = await josh_command.josh_run(['lane:open', issue], should_forward_stderr)
+
+	return opened.code === SUCCESS_EXIT_CODE ? opened.out : undefined
+}
+
 // The launch chain in-process. The CLI prints the pid; `backlog:drive` launches through this same
 // chain (joshuafolkken/kit#2508).
 async function launch_lane(context: LaunchContext): Promise<LaunchOutcome> {
-	const opened = await josh_command.josh_run(['lane:open', context.issue], should_forward_stderr)
+	const directory = await lane_directory(context.issue)
 
-	if (opened.code !== SUCCESS_EXIT_CODE) return UNOPENED
+	if (directory === undefined) return UNOPENED
 
-	if (!(await prepare(context.stash, opened.out))) return FAILED
+	if (!(await prepare(context.stash, directory))) return FAILED
 
 	const dispatched = await josh_command.josh_run(
 		['lane:dispatch', context.issue],

package/scripts/lane/lane-ledger.ts

@@ -0,0 +1,145 @@
+import { closeSync, constants, openSync, writeSync } from 'node:fs'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { json_value } from '#scripts/lib/json-value'
+import { run_carry } from '#scripts/run/carry/run-carry'
+import { z } from 'zod'
+
+// The measurement ledger the lane limit is tuned against (joshuafolkken/kit#3355): one JSON line per
+// lane merge, per finished `josh gate`, and per machine-load sample, read back by `josh lane:stats`.
+//
+// **Its own file rather than the run's event stream.** The stream is capped at 500 events and is
+// rewritten whole on every append, which is right for "where is the run" and wrong for a measurement
+// that spans days of one-a-minute load samples. This file is only ever appended to, so concurrent lanes
+// never lose each other's lines to a read-modify-write race.
+//
+// **Keyed on the common git directory, the event stream's key**, so a lane child's gate, the parent's
+// merge and the sampler all land in one ledger per repository. It sits in the temp root beside every
+// other josh record; a reboot clears it, which is why `docs/maintainers/lane-limit-measurement.md`
+// closes a period with `josh lane:stats` before one.
+
+const LEDGER_PREFIX = 'josh-lane-ledger-'
+const LEDGER_SUFFIX = '.jsonl'
+const LINE_SEPARATOR = '\n'
+const LEDGER_FILE_MODE = 0o600
+// The flags `detached-launch.ts` appends its log with, for the same deterministic shared-temp path.
+const { O_APPEND, O_CREAT, O_NOFOLLOW, O_WRONLY } = constants
+// eslint-disable-next-line no-bitwise -- POSIX open flags are a bit field; `||` here would be a bug
+const APPEND_FLAGS = O_WRONLY | O_APPEND | O_CREAT | O_NOFOLLOW
+
+const KIND = { MERGE: 'merge', GATE: 'gate', LOAD: 'load' } as const
+
+const merge_schema = z.object({ kind: z.literal(KIND.MERGE), at: z.string(), issue: z.number() })
+const gate_schema = z.object({
+	kind: z.literal(KIND.GATE),
+	at: z.string(),
+	elapsed_ms: z.number(),
+	is_passed: z.boolean(),
+})
+// `swap_mb` and `lanes` are optional because either read can fail on its own — a platform with no
+// swap reading, a `git worktree` call that did not answer — and a sample is still worth its load.
+const load_schema = z.object({
+	kind: z.literal(KIND.LOAD),
+	at: z.string(),
+	load: z.number(),
+	free_mb: z.number(),
+	swap_mb: z.number().optional(),
+	lanes: z.number().optional(),
+})
+const entry_schema = z.discriminatedUnion('kind', [merge_schema, gate_schema, load_schema])
+
+type LedgerEntry = z.infer<typeof entry_schema>
+type MergeEntry = z.infer<typeof merge_schema>
+type GateEntry = z.infer<typeof gate_schema>
+type LoadEntry = z.infer<typeof load_schema>
+
+function target_of(repository: string): string {
+	return stamp_file.stamp_path(LEDGER_PREFIX, repository, LEDGER_SUFFIX)
+}
+
+// The ledger of the repository this checkout belongs to, or `undefined` outside one. `git rev-parse`
+// rejects outside a repository, and `josh gate` resolves this before it runs a check, so the rejection
+// is read as "no ledger" rather than allowed to fail the gate it would only have measured.
+async function target(): Promise<string | undefined> {
+	try {
+		const repository = await run_carry.repository_directory()
+
+		return repository === undefined ? undefined : target_of(repository)
+	} catch {
+		return undefined
+	}
+}
+
+// **Append, never rewrite** — `O_APPEND` keeps each short line whole across concurrent writers, and
+// `O_NOFOLLOW` plus `stamp_file`'s ownership test keep a planted link or another account's file from
+// receiving it.
+function append(path: string, entry: LedgerEntry): void {
+	const descriptor = openSync(path, APPEND_FLAGS, LEDGER_FILE_MODE)
+
+	try {
+		if (stamp_file.is_own_regular_file(path)) {
+			writeSync(descriptor, `${JSON.stringify(entry)}${LINE_SEPARATOR}`)
+		}
+	} finally {
+		closeSync(descriptor)
+	}
+}
+
+// Best-effort: a measurement must never fail the gate or the merge it measures, so every error — no
+// repository, an unwritable temp root — is dropped.
+async function record(entry: LedgerEntry, path?: string): Promise<void> {
+	try {
+		const destination = path ?? (await target())
+
+		if (destination !== undefined) append(destination, entry)
+	} catch {
+		// Reporting is best-effort: a failed append is dropped rather than raised into the caller's work.
+	}
+}
+
+function now_iso(): string {
+	return new Date().toISOString()
+}
+
+// One finished `josh gate`, whether it passed or not — a failing gate cost the lane its time as well.
+async function record_gate(path: string, elapsed_ms: number, is_passed: boolean): Promise<void> {
+	await record({ kind: KIND.GATE, at: now_iso(), elapsed_ms, is_passed }, path)
+}
+
+async function record_merge(issue: number): Promise<void> {
+	await record({ kind: KIND.MERGE, at: now_iso(), issue })
+}
+
+function parse_line(line: string): LedgerEntry | undefined {
+	return entry_schema.safeParse(json_value.parse_or_undefined(line)).data
+}
+
+function is_present(entry: LedgerEntry | undefined): entry is LedgerEntry {
+	return entry !== undefined
+}
+
+// Every entry, oldest first. A malformed line — a write cut short — is skipped rather than making the
+// whole ledger unreadable, and an absent or unowned file is an empty ledger.
+function read_entries(path: string): ReadonlyArray<LedgerEntry> {
+	const raw = stamp_file.read_stamp_text(path)
+
+	if (raw === undefined) return []
+
+	return raw
+		.split(LINE_SEPARATOR)
+		.map((line) => parse_line(line.trim()))
+		.filter(is_present)
+}
+
+const lane_ledger = {
+	KIND,
+	append,
+	read_entries,
+	record,
+	record_gate,
+	record_merge,
+	target,
+	target_of,
+}
+
+export type { GateEntry, LedgerEntry, LoadEntry, MergeEntry }
+export { lane_ledger }

package/scripts/lane/lane-leftover.ts

@@ -59,7 +59,7 @@ function walk_files(directory: string, relative: string): Array<string> {
 	return readdirSync(path.join(directory, relative), { withFileTypes: true }).flatMap((entry) => {
 		const child = relative === '' ? entry.name : `${relative}/${entry.name}`
 
-		return entry.isDirectory() ? walk_files(directory, child) : [child]
+		return entry.isDirectory() ? walk_files(directory, child) : child
 	})
 }