@joshuafolkken/kit 1.1240.0 → 1.1373.0

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

@@ -1,11 +1,13 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
+import { backlogrun_launch } from '#scripts/backlog/backlogrun-launch'
+import { run_carry } from '#scripts/run/carry/run-carry'
 import { josh_environment_file } from './josh-environment-file'
 import { session_language, type Resolution } from './session-language'
 
 // `josh session:lang` — say, on stdout, which language this session writes in, so a
-// `SessionStart` / `UserPromptSubmit` hook injects the resolved value into context every turn
-// (joshuafolkken/kit#1903). Before this, `JOSH_SESSION_LANG` lived only in `.env` — a personal,
+// `SessionStart` / `UserPromptSubmit` hook injects the resolved value into context every turn.
+// Before this, `JOSH_SESSION_LANG` lived only in `.env` — a personal,
 // non-committed file the harness never loads into the process environment — so the value was
 // invisible unless the agent read the file itself, and a one-word prompt like `diag` had nothing to
 // infer a language from and drifted to the surrounding English.
@@ -18,32 +20,72 @@ import { session_language, type Resolution } from './session-language'
 // The line itself is a script-fixed string, so it stays English by the same rule that pins the
 // Telegram header labels and the `--notify-message` default (`CLAUDE.md` → "Output language").
 
+//
+// **The same hook carries the board rule while a `backlogrun` is live.** The rule
+// that a progress question is answered with `run:board --chat` is read only by the session driving a
+// run, so a session asked from the side never met it. The prompt is the one moment every session
+// shares, and the line is gated on the run being live, so a repository with no run pays nothing for
+// it. Live is `backlogrun_launch.is_running`'s answer, not a second reading of the records.
+
 const { DEFAULT_SESSION_LANG, ENV_KEY, resolve_session_lang } = session_language
-const ENGLISH_OPT_IN_LANG = 'en'
+
+const BOARD_LINE =
+	'A backlogrun is live here: answer a progress question with `pnpm josh run:board --chat`, verbatim in one code block.'
+
+interface LivePorts {
+	// The common git directory the run's records are keyed on; `undefined` outside a repository.
+	repository_directory: () => Promise<string | undefined>
+	is_running: (git_directory: string) => boolean
+}
+
+const LIVE_PORTS: LivePorts = {
+	repository_directory: run_carry.repository_directory,
+	is_running: backlogrun_launch.is_running,
+}
 
 // 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.
+// already in context every turn, so repeating it here only spent context on each prompt. The default
+// prints nothing — that resident line already names `ja`.
 function format_line(resolution: Resolution): string {
-	const suffix = resolution.is_default
-		? ` (default; set ${ENV_KEY}=${ENGLISH_OPT_IN_LANG} for English)`
-		: ''
+	if (resolution.is_default) return ''
 
-	return `Session language (${ENV_KEY}): ${resolution.lang}${suffix}`
+	return `Session language (${ENV_KEY}): ${resolution.lang}`
 }
 
-function main(): void {
+// A throw is answered `false`: a hook that failed here would cost the prompt its language line too.
+async function is_run_live(ports: LivePorts = LIVE_PORTS): Promise<boolean> {
+	try {
+		const git_directory = await ports.repository_directory()
+
+		return git_directory !== undefined && ports.is_running(git_directory)
+	} catch {
+		return false
+	}
+}
+
+function prompt_lines(resolution: Resolution, is_live: boolean): Array<string> {
+	return [format_line(resolution), is_live ? BOARD_LINE : ''].filter((line) => line !== '')
+}
+
+async function main(): Promise<void> {
 	josh_environment_file.load_environment_file()
-	console.info(format_line(resolve_session_lang()))
+	const lines = prompt_lines(resolve_session_lang(), await is_run_live())
+
+	for (const line of lines) console.info(line)
 }
 
 const session_language_cli = {
+	BOARD_LINE,
 	DEFAULT_SESSION_LANG,
 	ENV_KEY,
 	format_line,
+	is_run_live,
+	prompt_lines,
 	resolve_session_lang,
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) main()
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main()
 
+export type { LivePorts }
 export { session_language_cli }

package/scripts/josh/session-language.ts

@@ -5,7 +5,7 @@
 // prints nothing (`build-hooks.ts` → "`splitting: true` is load-bearing").
 //
 // Unset and empty resolve to `ja`, because a worktree without a `.env`, a cloud session and a
-// consumer repository are exactly where the drift recurs (joshuafolkken/kit#1903).
+// consumer repository are exactly where the drift recurs.
 
 const ENV_KEY = 'JOSH_SESSION_LANG'
 const DEFAULT_SESSION_LANG = 'ja'

package/scripts/josh/stamp-file.ts

@@ -6,8 +6,8 @@ import { PLATFORM_TEMP_ROOT } from './platform-temporary'
 
 // A small record one josh command writes and another reads, kept per checkout in the temp directory.
 //
-// Extracted from `scripts/eval/eval-stamp.ts` when `josh latest:scope` needed the same handoff
-// (joshuafolkken/kit#1215). The mechanics below are not boilerplate — the symlink defense on the
+// Extracted from `scripts/eval/eval-stamp.ts` when `josh latest:scope` needed the same handoff.
+// The mechanics below are not boilerplate — the symlink defense on the
 // write, the ownership check on the read, and the deterministic per-checkout path are each load
 // bearing — so a second copy of them is the clone `CLAUDE.md` prohibits. What differs between the
 // two records is their *payload* and the question asked of it, and that is all either module keeps.
@@ -42,7 +42,7 @@ function digest(content: Buffer | string): string {
 // without this two accounts would name one file — and the second one's unlink of a file the first owns
 // fails on the sticky directory, ending its command. Folding the account in keeps accidental
 // collisions apart; a hostile local account can still pre-create a predictable name, which fails the
-// write rather than redirecting it (joshuafolkken/kit#1909). Windows has no `getuid` and keeps the
+// write rather than redirecting it. Windows has no `getuid` and keeps the
 // per-user `os.tmpdir()`, so it contributes an empty account.
 function account_key(): string {
 	return String(process.getuid?.() ?? '')
@@ -56,17 +56,17 @@ function account_key(): string {
 // `TMPDIR`.** A record this module keeps is read by a *different* process than wrote it — the second
 // half of a handoff — and `os.tmpdir()` honors each process's own `TMPDIR`, so a session a
 // `run:wake` or a `lane:dispatch` launched resolves a different directory than its launcher and the
-// handoff is lost (joshuafolkken/kit#1909). The keyed digest below already keeps one checkout apart
+// handoff is lost. The keyed digest below already keeps one checkout apart
 // from another; the root is what has to stop moving per process, which `platform-temporary.ts` pins.
 //
 // **`root` is what the record is keyed to, and the right answer differs per caller.** `PACKAGE_DIR`
 // is the default because `josh eval` measures the kit package's own files. A record about the
 // *project* must key on `PROJECT_ROOT` instead: a globally installed `josh` has one `PACKAGE_DIR`
 // for every project on the machine, so keying on it would let a run in one project answer for
-// another (joshuafolkken/kit#1215).
+// another.
 //
 // **`suffix` is what the file is, not decoration.** Every record here was JSON until `josh gate`
-// needed to keep another tool's output verbatim (joshuafolkken/kit#1227), and a log named `.json`
+// needed to keep another tool's output verbatim, and a log named `.json`
 // tells every reader — a person, an editor, a `less` — that it is something it is not.
 function stamp_path(
 	prefix: string,
@@ -95,17 +95,46 @@ function write_stamp(target: string, payload: unknown): string {
 	return write_exclusively(target, JSON.stringify(payload))
 }
 
+// The read side of the write's problem. A record is trusted to say something is still current, so a
+// planted one suppresses the work the check exists to force. `lstatSync` reports the link rather than
+// what it points at, and it throws where the path is simply absent — both of which are "no record".
+// `getuid` is missing on Windows, where a shared temp directory is not the same hazard; the check
+// reduces to "is it a regular file" there.
+function is_own_regular_file(source: string): boolean {
+	const stats = lstatSync(source)
+
+	if (!stats.isFile()) return false
+
+	const uid = process.getuid?.()
+
+	return uid === undefined || stats.uid === uid
+}
+
+// A regular file at `target` that another account owns. An absent path or a symlink is not one: the
+// replace below swaps either out without following it.
+function is_foreign_file(target: string): boolean {
+	try {
+		return lstatSync(target).isFile() && !is_own_regular_file(target)
+	} catch {
+		return false
+	}
+}
+
 // Mutable coordination state cannot disappear between an unlink and its replacement: a reader that
 // mistakes that gap for "no child" can start the same generation twice. The temporary file lives
 // beside the target, uses the same exclusive/symlink-safe create, and rename publishes it atomically.
-function replace_stamp(target: string, payload: unknown): string {
+// `rename` replaces the path itself rather than following a symlink planted there, so the write still
+// never lands somewhere else; a regular file another account owns is refused before it is replaced,
+// the same answer the unlink gives on a sticky temp directory.
+function replace_text_stamp(target: string, text: string): string {
+	if (is_foreign_file(target)) {
+		throw new Error(`refusing to replace another account's file: ${target}`)
+	}
+
 	const temporary = `${target}.${String(process.pid)}.${randomUUID()}`
 
 	try {
-		writeFileSync(temporary, JSON.stringify(payload), {
-			flag: STAMP_CREATE_FLAG,
-			mode: STAMP_FILE_MODE,
-		})
+		writeFileSync(temporary, text, { flag: STAMP_CREATE_FLAG, mode: STAMP_FILE_MODE })
 		renameSync(temporary, target)
 
 		return target
@@ -114,8 +143,12 @@ function replace_stamp(target: string, payload: unknown): string {
 	}
 }
 
+function replace_stamp(target: string, payload: unknown): string {
+	return replace_text_stamp(target, JSON.stringify(payload))
+}
+
 // The same write for a payload that is already text. `josh gate`'s log is another tool's output read
-// by a person or by an agent's `tail` (joshuafolkken/kit#1227), and JSON-encoding it would put `\n`
+// by a person or by an agent's `tail`, and JSON-encoding it would put `\n`
 // escapes between the reader and the thing they came to read. **It shares the body above rather than
 // repeating it**: the unlink-then-create-exclusively pair is the symlink defense, and a second copy
 // of it is the clone `CLAUDE.md` prohibits.
@@ -124,7 +157,7 @@ function write_text_stamp(target: string, text: string): string {
 }
 
 // `write_stamp` for a record whose *absence* is what the caller checked, and which two processes may
-// therefore try to create at once (joshuafolkken/kit#1091). It does **not** unlink first, so `wx` is
+// therefore try to create at once. It does **not** unlink first, so `wx` is
 // doing the job it exists for: the second writer loses and is told so, rather than both being told
 // they won. `false` is that loss and never an error, because "someone else got here first" is an
 // answer; anything else still throws, since a record that could not be written for another reason
@@ -145,28 +178,13 @@ function create_stamp(target: string, payload: unknown): boolean {
 }
 
 // The counterpart to `write_stamp`, for a record that means something only while it exists — the
-// in-flight gate marker `josh gate` clears when its checks finish (joshuafolkken/kit#1242). `force`
+// in-flight gate marker `josh gate` clears when its checks finish. `force`
 // makes an absent path a success, because "there is no record" is the state the caller wanted; and
 // `rmSync` removes a symlink rather than following it, the same reason the write unlinks first.
 function remove_stamp(target: string): void {
 	rmSync(target, { force: true })
 }
 
-// The read side of the write's problem. A record is trusted to say something is still current, so a
-// planted one suppresses the work the check exists to force. `lstatSync` reports the link rather than
-// what it points at, and it throws where the path is simply absent — both of which are "no record".
-// `getuid` is missing on Windows, where a shared temp directory is not the same hazard; the check
-// reduces to "is it a regular file" there.
-function is_own_regular_file(source: string): boolean {
-	const stats = lstatSync(source)
-
-	if (!stats.isFile()) return false
-
-	const uid = process.getuid?.()
-
-	return uid === undefined || stats.uid === uid
-}
-
 // `undefined` rather than a throw or an empty string: "there is no record" and "the record says
 // nothing has to be done" are two different answers, and only the first of them is a reason to act.
 function read_stamp_text(source: string): string | undefined {
@@ -185,6 +203,7 @@ const stamp_file = {
 	is_own_regular_file,
 	read_stamp_text,
 	replace_stamp,
+	replace_text_stamp,
 	remove_stamp,
 	stamp_path,
 	write_stamp,

package/scripts/josh/stamp-record.ts

@@ -0,0 +1,57 @@
+// What every aged record `stamp-file.ts` keeps is asked on the read: is it there, can it be read, and
+// has its bound run out.
+//
+// `run-carry.ts`, `run-cut.ts` and `run-hold.ts` each carried the expiry below, and the first two the
+// classification as well. What an unparsable or a future time means is one decision, so it is made
+// here once; what differs between the records is their payload, their timestamp field and their bound,
+// and that is all a `StampRecordSpec` names.
+
+interface StampRecordSpec<T> {
+	parse: (raw: string) => T | undefined
+	timestamp_of: (record: T) => string
+	max_age_ms: number
+}
+
+type StampRecordRead<T> =
+	| { kind: 'none' }
+	| { kind: 'carried'; record: T }
+	| { kind: 'expired'; record: T }
+	| { kind: 'unreadable' }
+
+const NONE_READ = { kind: 'none' } as const
+const UNREADABLE_READ = { kind: 'unreadable' } as const
+
+// **A time that is not a date is older than any bound, not current.** It passes a schema — it is a
+// string — so reading it as current would leave a record nothing can ever expire, which is the one
+// state a bound exists to make impossible. A time ahead of `now` (a skewed clock) has a negative age
+// and is not older; the bound is exclusive, so a record exactly at it is still current.
+function is_older_than(iso: string, max_age_ms: number, now: Date): boolean {
+	const at = Date.parse(iso)
+
+	if (Number.isNaN(at)) return true
+
+	return now.getTime() - at > max_age_ms
+}
+
+// **A record that cannot be read is `unreadable`, never `none`.** Absent is none; present and
+// unparseable is the state a guard must not fall open on.
+function classify<T>(
+	raw: string | undefined,
+	spec: StampRecordSpec<T>,
+	now: Date,
+): StampRecordRead<T> {
+	if (raw === undefined) return NONE_READ
+
+	const record = spec.parse(raw)
+
+	if (record === undefined) return UNREADABLE_READ
+
+	const is_expired = is_older_than(spec.timestamp_of(record), spec.max_age_ms, now)
+
+	return { kind: is_expired ? 'expired' : 'carried', record }
+}
+
+const stamp_record = { classify, is_older_than }
+
+export { stamp_record }
+export type { StampRecordRead, StampRecordSpec }

package/scripts/lane/lane-await.ts

@@ -1,15 +1,21 @@
 import { spawnSync } from 'node:child_process'
 import { setTimeout as sleep } from 'node:timers/promises'
 import { parseArgs } from 'node:util'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { PROBE_TIMEOUT_MS } from '#scripts/lib/timeouts'
-import { run_liveness } from '#scripts/run/run-liveness'
+import {
+	PROCESS_ALIVE,
+	PROCESS_NONE,
+	PROCESS_UNKNOWN,
+	run_liveness,
+	type ProcessTrace,
+} from '#scripts/run/run-liveness'
 import { lane_child_invocation } from './lane-child-invocation'
 import { lane_handoff } from './lane-handoff'
 
 // Detached lane children are not harness-tracked processes, so their completion fires no
 // re-invocation event in the parent's session. Without a blocking wait the parent notices only
-// on the next heartbeat interval -- up to 15 minutes after the fact in the measured case
-// (joshuafolkken/kit#2113).
+// on the next heartbeat interval -- up to 15 minutes after the fact.
 //
 // **The re-confirm delay is the one value the caller must not be left to choose.** A process that
 // disappears briefly and reappears (the pre-gate boundary cut, where one process exits and a
@@ -22,12 +28,12 @@ const RECONFIRM_MS = 15_000
 const DEFAULT_POLL_MS = 5000
 const NEVER_APPEARED_TIMEOUT_MS = 600_000
 const MS_PER_SECOND = 1000
-const ISSUE_PATTERN = /^[1-9]\d*$/u
 const PROCESS_FOUND = 0
+const PROCESS_NOT_FOUND = 1
 
 // `is_settled` is read once, when the wait starts: a child that ended between two `lane:await` calls
 // never appears in the second one, and only its settled issue tells it apart from one not yet
-// launched (joshuafolkken/kit#3133).
+// launched.
 interface AwaitState {
 	appeared: boolean
 	disappeared_at: number | undefined
@@ -52,6 +58,8 @@ interface AwaitOptions {
 	poll_ms?: number
 	reconfirm_ms?: number
 	never_appeared_timeout_ms?: number
+	now?: () => number
+	sleep?: (ms: number) => Promise<void>
 }
 
 interface CheckConfig {
@@ -63,18 +71,28 @@ interface CheckConfig {
 interface RunConfig extends CheckConfig {
 	is_settled: (issue: string) => Promise<boolean>
 	poll_ms: number
+	now: () => number
+	sleep: (ms: number) => Promise<void>
 }
 
-function is_process_running_default(issue: string): boolean {
+// Three answers, not two: only pgrep's own "no match" exit is `none`. A pgrep that failed or hit its
+// timeout never looked, and `run:liveness` answers `undetermined` for it rather than booking a live
+// child as stopped.
+function process_trace_default(issue: string): ProcessTrace {
 	const pattern = lane_child_invocation.process_pattern(issue)
 	const result = spawnSync('pgrep', ['-f', pattern], {
 		encoding: 'utf8',
 		timeout: PROBE_TIMEOUT_MS,
 	})
 
-	if (result.status === PROCESS_FOUND) return true
+	if (result.status === PROCESS_FOUND) return PROCESS_ALIVE
+	if (lane_handoff.is_ship_running(issue, process.cwd())) return PROCESS_ALIVE
+
+	return result.status === PROCESS_NOT_FOUND ? PROCESS_NONE : PROCESS_UNKNOWN
+}
 
-	return lane_handoff.is_ship_running(issue, process.cwd())
+function is_process_running_default(issue: string): boolean {
+	return process_trace_default(issue) === PROCESS_ALIVE
 }
 
 // The same positive evidence `run:liveness` answers `settled` on: the issue closed, or it was parked.
@@ -101,7 +119,10 @@ function is_valid(raw: RawAwaitArguments): boolean {
 	const { owner } = raw.values
 	const numbers = owner === undefined ? raw.positionals : [...raw.positionals, owner]
 
-	return raw.positionals.length > 0 && numbers.every((value) => ISSUE_PATTERN.test(value))
+	return (
+		raw.positionals.length > 0 &&
+		numbers.every((value) => issue_number_shape.is_issue_number(value))
+	)
 }
 
 // The issues to wait on and the waiting session's pid, or `undefined` for anything else.
@@ -142,6 +163,8 @@ function resolve_options(options: AwaitOptions): RunConfig {
 	return {
 		is_running: options.is_running ?? is_process_running_default,
 		is_settled: options.is_settled ?? is_settled_default,
+		now: options.now ?? Date.now,
+		sleep: options.sleep ?? sleep,
 		...resolve_timing(options),
 	}
 }
@@ -225,12 +248,12 @@ async function wait_for_any(
 	const states = await make_states(issues, config.is_settled)
 
 	for (;;) {
-		const completed = check_any(states, Date.now(), config)
+		const completed = check_any(states, config.now(), config)
 
 		if (completed !== undefined) return completed
 
 		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
-		await sleep(config.poll_ms)
+		await config.sleep(config.poll_ms)
 	}
 }
 
@@ -240,6 +263,7 @@ const lane_await = {
 	check_issue,
 	is_process_running_default,
 	parse_arguments,
+	process_trace_default,
 	wait_for_any,
 }
 

package/scripts/lane/lane-cache.ts

@@ -8,15 +8,15 @@ import {
 	type GateCacheSpec,
 } from '#scripts/josh/josh-command-types'
 
-// Warming a fresh lane's verification caches from the main checkout (joshuafolkken/kit#1849).
+// Warming a fresh lane's verification caches from the main checkout.
 //
 // `git worktree add` writes a checkout and nothing beside it, and the three caches the gate reads —
 // `.eslintcache`, `.tsbuildinfo`, `.cspellcache` — are all git-ignored, so a new lane has none of
-// them and only its *first* `josh gate` runs fully cold (measured at 353.9 s against 27.5 s warm,
-// joshuafolkken/kit#1839). The initial seed warms that run; the per-tool sync below keeps the
-// portable ESLint and CSpell caches current afterwards (#2060).
+// them and only its *first* `josh gate` runs fully cold (several minutes against well under a minute
+// warm). The initial seed warms that run; the per-tool sync below keeps the portable ESLint and
+// CSpell caches current afterwards.
 //
-// Content hashes make stale entries safe, but do not by themselves make a cache portable (#2060).
+// Content hashes make stale entries safe, but do not by themselves make a cache portable.
 // ESLint keys entries by absolute file path, so its JSON is rebased while cspell's relative keys and
 // TypeScript's build info move raw. The spec in `josh-command-types.ts` is the one declaration of
 // which treatment and which continuous sharing each gate cache receives.
@@ -103,7 +103,7 @@ function seed_caches(source_root: string, destination: string): void {
 /**
  * Copy the pre-built hook bundles (`dist/hooks/`) from `source_root` into `destination`, so a fresh
  * lane's child runs each Claude Code hook off `node dist/hooks/<name>.js` rather than the slower
- * `pnpm josh …` fallback (joshuafolkken/kit#2160). The bundles are git-ignored, so a lane's work tree
+ * `pnpm josh …` fallback. The bundles are git-ignored, so a lane's work tree
  * never carries them and every hook falls back without this seed.
  *
  * Best-effort, exactly like `seed_caches`: a source with no bundles (a checkout that never ran

package/scripts/lane/lane-capacity.ts

@@ -1,14 +1,14 @@
+import { lane_limit_override } from './lane-limit-override'
 import type { LaneEnvironment } from './lane-paths'
 import { lane_seed_policy } from './lane-seed'
 
-// How many lanes one repository may run at once, and how many of them are free
-// (joshuafolkken/kit#1491).
+// How many lanes one repository may run at once, and how many of them are free.
 //
 // **Nothing here knows what a lane holds.** The limit is a number, the occupancy is a number, and
 // the answer is a number — so the same pool serves an epic's children, several epics' children at
 // once, or anything else a scheduler decides to put in a lane. Threading an epic through this module
-// is what would have to be undone the first time two epics run together, and the whole reason
-// joshuafolkken/kit#1491 built the scheduler epic-free from the start.
+// is what would have to be undone the first time two epics run together, which is why the scheduler
+// is epic-free.
 //
 // **It is a ceiling, not a prediction.** Six lanes does not say six children will run at once; it
 // says a seventh will not start. What actually runs is bounded by what is runnable, by the port
@@ -33,40 +33,55 @@ type LimitChoice = { kind: 'limit'; limit: number } | { kind: 'problem'; problem
 //
 // Blank is unset, not invalid: an `.env` line left as `JOSH_LANE_LIMIT=` is a variable nobody
 // configured, exactly as `lane_paths.lane_root` reads a blank root.
-function read_limit(raw: string | undefined): LimitChoice {
+//
+// `name` is what the problem names: `josh lane:limit` reads its argument by the same rule.
+function read_limit(raw: string | undefined, name: string): LimitChoice {
 	const trimmed = raw?.trim() ?? ''
 
 	if (trimmed === '') return { kind: 'limit', limit: DEFAULT_LANE_LIMIT }
 
 	if (!POSITIVE_INTEGER.test(trimmed)) {
-		return {
-			kind: 'problem',
-			problem: `${LANE_LIMIT_KEY} must be a positive integer, not "${trimmed}"`,
-		}
+		return { kind: 'problem', problem: `${name} must be a positive integer, not "${trimmed}"` }
 	}
 
 	return { kind: 'limit', limit: Number(trimmed) }
 }
 
-function lane_limit(environment: LaneEnvironment = process.env): LimitChoice {
-	return read_limit(environment[LANE_LIMIT_KEY])
+// **A live run's `lane:limit` override outranks the environment**: a running
+// parent keeps the environment it started with, so the override is the only way its limit moves. This
+// stays the one place the limit is read; the override reader is injected so a test reads none.
+async function lane_limit(
+	environment: LaneEnvironment = process.env,
+	read_override: () => Promise<number | undefined> = lane_limit_override.read_override,
+): Promise<LimitChoice> {
+	const override = await read_override()
+
+	if (override !== undefined) return { kind: 'limit', limit: override }
+
+	return read_limit(environment[LANE_LIMIT_KEY], LANE_LIMIT_KEY)
+}
+
+// **A limit above the seat count is capped at the seats**. `lane:open` refuses
+// a tenth lane however high the limit is set, so a limit past the seats offers launches bound to be
+// refused.
+function seated_limit(limit: number): number {
+	return Math.min(limit, lane_seed_policy.LAST_LANE_SEAT)
 }
 
 // Never negative: a repository holding more `in-progress` issues than the limit allows — the limit
 // was lowered, or a stale label outlived its run — has no free lane, and a negative count read as
 // "how many to offer" would be a slice nobody meant.
-//
-// **A limit above the seat count is capped at the seats** (joshuafolkken/kit#3027). `lane:open` refuses
-// a tenth lane however high `JOSH_LANE_LIMIT` is set, so counting free lanes past the seats offers a
-// launch that is bound to be refused.
 function free_lanes(limit: number, occupied: number): number {
-	return Math.max(NO_LANES, Math.min(limit, lane_seed_policy.LAST_LANE_SEAT) - occupied)
+	return Math.max(NO_LANES, seated_limit(limit) - occupied)
 }
 
 const lane_capacity = {
 	LANE_LIMIT_KEY,
-	lane_limit,
 	free_lanes,
+	lane_limit,
+	read_limit,
+	seated_limit,
 }
 
+export type { LimitChoice }
 export { lane_capacity }

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

@@ -1,4 +1,5 @@
-import { run_issue_number } from '#scripts/run/run-issue-number'
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { run_ship_next, type ShipResume } from '#scripts/run/ship/run-ship-next'
 import type { Stage } from '#scripts/run/ship/run-ship-stage'
 
@@ -8,7 +9,7 @@ interface ShipStop extends ShipResume {
 
 const CHILD_INVOCATION = 'fullrun'
 const RESUME_GUIDE = '.claude/skills/workflow-commands/pre-gate-cut.md'
-// What a detached `josh ship --detach` supervisor's command line carries (joshuafolkken/kit#2428). It ends
+// What a detached `josh ship --detach` supervisor's command line carries. It ends
 // with the `"<title> #<N>"` title on purpose, so the liveness pattern below finds it by the same trailing
 // anchor it finds a child by. **The script path alone is not enough**: where the dispatcher is TypeScript
 // (kit itself) `josh ship` runs in-process, so no process ever carries `run-ship-cli.ts` — the `pnpm josh
@@ -16,57 +17,58 @@ const RESUME_GUIDE = '.claude/skills/workflow-commands/pre-gate-cut.md'
 const SHIP_PROCESS = String.raw`(josh(\.[jt]s)? ship|run-ship-cli\.ts)`
 
 function child_invocation(issue: string): string {
-	run_issue_number.require_issue_number(issue)
+	issue_number_shape.require_issue_number(issue)
 
-	return `${CHILD_INVOCATION} #${issue}`
+	return `${CHILD_INVOCATION} ${issue_cite.plain(issue)}`
 }
 
 // The `pgrep -f` pattern that finds a running child: the invocation is always the last argument of
 // its command line — the resume prompts below end with it on purpose — so the anchor matches every
-// launch of `#<N>` and never `#<N>0` (joshuafolkken/kit#2421).
+// launch of `#<N>` and never `#<N>0`.
 //
-// **A detached ship supervisor counts as the child** (joshuafolkken/kit#2428). The agent ends once it has
+// **A detached ship supervisor counts as the child**. The agent ends once it has
 // handed the post-implementation region to `josh ship --detach`, and the parent books a lane whose
 // pattern stopped matching as finished — parking an issue that was still shipping. The supervisor's
 // command line ends with its `#<N>` title, so the one extended pattern covers both, and the wait, the
 // liveness read and the reaper keep searching with a single pattern.
 function process_pattern(issue: string): string {
-	run_issue_number.require_issue_number(issue)
+	issue_number_shape.require_issue_number(issue)
 
-	return `(${CHILD_INVOCATION}|${SHIP_PROCESS} .*) #${issue}$`
+	return `(${CHILD_INVOCATION}|${SHIP_PROCESS} .*) ${issue_cite.plain(issue)}$`
 }
 
 function resume_invocation(issue: string): string {
-	const preamble = `Resuming the lane child for issue #${issue} — do not re-read the workflow-commands entry documents (SKILL.md, fullrun.md). Run \`pnpm josh run:cut --resume ${issue}\` before anything else and follow the matching verdict in ${RESUME_GUIDE}: \`resume\` goes to the gate, \`resume-impl\` continues implementation. Only on \`fresh\` proceed as an ordinary`
+	const preamble = `Resuming the lane child for issue ${issue_cite.plain(issue)} — do not re-read the workflow-commands entry documents (SKILL.md, fullrun.md). Run \`pnpm josh run:cut --resume ${issue}\` before anything else and follow the matching verdict in ${RESUME_GUIDE}: \`resume\` goes to the gate, \`resume-impl\` continues implementation. Only on \`fresh\` proceed as an ordinary`
 
 	return `${preamble} ${child_invocation(issue)}`
 }
 
-// The prompt an `outage` re-dispatch gives a resumed child (joshuafolkken/kit#2317). Its session was
+// The prompt an `outage` re-dispatch gives a resumed child. Its session was
 // relaunched with `--resume`, so its full context is already loaded — the preamble tells it not to
 // re-read the entry documents and to find where it stopped with `run:step`, redoing only the last
 // action if it did not complete.
 //
 // **It ends with `child_invocation` on purpose, not as decoration** — for the same reason
-// `resume_invocation` does: the parent's liveness poll is `pgrep -laf "<invocation>$"`, so the trailing
+// `resume_invocation` does: the parent's liveness read (`run:liveness`, `lane:await`) matches
+// `process_pattern` against the command line, so the trailing
 // `fullrun #<N>` keeps the relaunched process matching, and it is the ordinary run the child carries on.
 function outage_resume_invocation(issue: string): string {
-	const preamble = `Resuming the lane child for issue #${issue} after an API disconnection — your session was restored with its full context, so do not re-read the workflow-commands entry documents (SKILL.md, fullrun.md). Continue the run from where it stopped: run \`pnpm josh run:step ${issue}\` to find the next action, redoing only the last step if it did not complete.`
+	const preamble = `Resuming the lane child for issue ${issue_cite.plain(issue)} after an API disconnection — your session was restored with its full context, so do not re-read the workflow-commands entry documents (SKILL.md, fullrun.md). Continue the run from where it stopped: run \`pnpm josh run:step ${issue}\` to find the next action, redoing only the last step if it did not complete.`
 
 	return `${preamble} ${child_invocation(issue)}`
 }
 
 // The prompt a lane child is relaunched with when its detached ship supervisor stopped at a failed
-// stage (joshuafolkken/kit#2428) — a red gate, a High/Medium review, a failed push or red CI. The agent
+// stage — a red gate, a High/Medium review, a failed push or red CI. The agent
 // ended at the hand-off, so this is how control comes back to one: it reads the stopped report, fixes it
 // and hands the region back. It ends with `child_invocation` for the reason `resume_invocation` does —
 // the parent's poll keeps matching the relaunched process.
 //
-// **A known stage puts the next command in the prompt** (joshuafolkken/kit#2964), so the relaunched
+// **A known stage puts the next command in the prompt**, so the relaunched
 // session runs it rather than re-deriving it from `chain-rule.md`. An OpenAI lane's supervisor sees only
 // that the ship failed, not where, so without a stage the prompt points at `run:step` as before.
 function ship_stop_invocation(issue: string, stop?: ShipStop): string {
-	const opening = `Resuming the lane child for issue #${issue} after its detached ship supervisor stopped at a failed stage — do not re-read the workflow-commands entry documents (SKILL.md, fullrun.md).`
+	const opening = `Resuming the lane child for issue ${issue_cite.plain(issue)} after its detached ship supervisor stopped at a failed stage — do not re-read the workflow-commands entry documents (SKILL.md, fullrun.md).`
 	const next =
 		stop === undefined
 			? `Run \`pnpm josh run:step ${issue}\` and read the stopped report it names, fix what stopped the ship, then hand the region back per chain-rule.md.`