@joshuafolkken/kit 1.1455.0 → 1.1514.0

package/scripts/agent/agent-safe-text.ts

@@ -0,0 +1,60 @@
+// The text an agent launch may carry: a model id, an effort and a prompt, refused when empty, over
+// length or carrying a control character, so nothing a value holds can inject a further argument.
+
+const FIRST_PRINTABLE_CODE = 0x20
+const DELETE_CODE = 0x7f
+const FIRST_CODE_POINT = 0
+const EMPTY_LENGTH = 0
+const MAX_VALUE_LENGTH = 4096
+const LINE_FEED = '\n'
+const SPACE = ' '
+
+function is_control_character(character: string): boolean {
+	const code = character.codePointAt(FIRST_CODE_POINT) ?? FIRST_PRINTABLE_CODE
+
+	return code < FIRST_PRINTABLE_CODE || code === DELETE_CODE
+}
+
+function is_line_feed(character: string): boolean {
+	return character === LINE_FEED
+}
+
+function is_never_allowed(): boolean {
+	return false
+}
+
+function is_refused(character: string, is_allowed: (character: string) => boolean): boolean {
+	return is_control_character(character) && !is_allowed(character)
+}
+
+function is_safe_text(value: string, is_allowed: (character: string) => boolean): boolean {
+	if (value.length === EMPTY_LENGTH || value.length > MAX_VALUE_LENGTH) return false
+
+	for (const character of value) if (is_refused(character, is_allowed)) return false
+
+	return true
+}
+
+function is_safe_value(value: string): boolean {
+	return is_safe_text(value, is_never_allowed)
+}
+
+// **An agent's prompt is the one value a line break belongs in.** A ship-stop prompt carries the failed
+// output's lines (joshuafolkken/kit#3964); every other control character is refused as in any value.
+function is_safe_prompt(value: string): boolean {
+	return is_safe_text(value, is_line_feed)
+}
+
+function printable_character(character: string): string {
+	return is_refused(character, is_line_feed) ? SPACE : character
+}
+
+// Command output made fit for a prompt: every control character but a line break becomes a space, so
+// the text passes `is_safe_prompt` whatever the command printed.
+function printable(text: string): string {
+	return Array.from(text, printable_character).join('')
+}
+
+const agent_safe_text = { MAX_VALUE_LENGTH, is_safe_prompt, is_safe_value, printable }
+
+export { agent_safe_text }

package/scripts/agent/claude-agent-argv.ts

@@ -6,6 +6,7 @@ import {
 	type AgentProfile,
 	type AgentRole,
 } from './agent-role-profile'
+import { lane_instructions } from './lane-instructions'
 
 const AGENT_COMMAND = 'claude'
 // **The permission mode is passed, not left to the checkout's `.claude/settings.json`.** Claude Code
@@ -63,6 +64,7 @@ const PROJECT_MCP_FILE = '.mcp.json'
 interface ClaudeArgv {
 	command: string
 	args: ReadonlyArray<string>
+	ends_with_prompt: true
 }
 
 type ClaudeArgvResult =
@@ -87,6 +89,14 @@ function tool_flags(cwd: string = process.cwd()): ReadonlyArray<string> {
 	return [TOOLS_FLAG, LAUNCHED_TOOLS.join(','), ...mcp_flags]
 }
 
+// **A lane child and a review session start from the lane instruction set** (`lane-instructions.ts`);
+// the scheduler keeps `CLAUDE.md`, because it is the one that stops and asks a person.
+function instruction_flags(profile: AgentProfile, cwd?: string): ReadonlyArray<string> {
+	if (profile.role === agent_role_profile.SCHEDULER) return []
+
+	return lane_instructions.flags(cwd)
+}
+
 function build(
 	invocation: string,
 	profile: AgentProfile,
@@ -98,6 +108,7 @@ function build(
 		args: [
 			...AGENT_FLAGS,
 			...tool_flags(cwd),
+			...instruction_flags(profile, cwd),
 			...session_id_flags(session_id),
 			MODEL_FLAG,
 			profile.model,
@@ -105,6 +116,7 @@ function build(
 			profile.effort,
 			invocation,
 		],
+		ends_with_prompt: true,
 	}
 }
 
@@ -121,6 +133,7 @@ function build_resume(
 		args: [
 			...AGENT_FLAGS,
 			...tool_flags(cwd),
+			...instruction_flags(profile, cwd),
 			RESUME_FLAG,
 			session_id,
 			MODEL_FLAG,
@@ -129,6 +142,7 @@ function build_resume(
 			profile.effort,
 			invocation,
 		],
+		ends_with_prompt: true,
 	}
 }
 

package/scripts/agent/codex-agent-argv.ts

@@ -19,6 +19,7 @@ const LEDGER_DIRECTORY = path.dirname(OBSERVATION_LEDGER_DIRECTORY)
 interface CodexArgv {
 	command: string
 	args: ReadonlyArray<string>
+	ends_with_prompt: true
 }
 
 function effort_config(profile: AgentProfile): string {
@@ -47,8 +48,13 @@ function ledger_arguments(
 	common_directory: string | undefined,
 	profile: AgentProfile,
 ): ReadonlyArray<string> {
-	if (common_directory === undefined || profile.role !== agent_role_profile.WORKER) return []
-	if (path.basename(common_directory) !== GIT_DIRECTORY) return []
+	if (
+		common_directory === undefined ||
+		profile.role !== agent_role_profile.WORKER ||
+		path.basename(common_directory) !== GIT_DIRECTORY
+	) {
+		return []
+	}
 
 	const directory = path.join(path.dirname(common_directory), LEDGER_DIRECTORY)
 
@@ -86,6 +92,7 @@ function build(invocation: string, profile: AgentProfile, cwd?: string): CodexAr
 			JSON_FLAG,
 			invocation,
 		],
+		ends_with_prompt: true,
 	}
 }
 

package/scripts/agent/lane-instructions.ts

@@ -0,0 +1,144 @@
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { cost_tokens } from '#scripts/cost-runtime/cost-tokens'
+import { document_section } from '#scripts/document/document-section'
+import { distributed_paths } from '#scripts/init/distributed-paths'
+import { find_package_directory } from '#scripts/josh/package-directory'
+import { stamp_file } from '#scripts/josh/stamp-file'
+
+interface LaneSet {
+	text: string
+	rules_path: string
+}
+
+// **A headless lane child or review session starts from the lane instruction set, not `CLAUDE.md`.**
+// `CLAUDE.md` carries rules only an interactive session can act on — consultation versus execution,
+// explicit workflow invocation, stop notifications — and every request re-reads it. The lane document
+// names the rules a lane does need by `CLAUDE.md` heading or bold label, and each `include` line is
+// expanded from the launch checkout's own `CLAUDE.md` here, so the rule text keeps one source (#3929).
+const LANE_DOCUMENT = 'prompts/collaboration-workflow/lane-instructions.md'
+const RULES_FILE = 'CLAUDE.md'
+// `AGENTS.md` only points at `CLAUDE.md`, and Claude Code loads it once `CLAUDE.md` is excluded.
+const POINTER_FILE = 'AGENTS.md'
+const INCLUDE_PATTERN = /^<!-- include: CLAUDE\.md → "(?<wanted>.+)" -->$/u
+const PROMPT_FILE_FLAG = '--append-system-prompt-file'
+const SETTINGS_FLAG = '--settings'
+const PROMPT_FILE_PREFIX = 'josh-lane-instructions-'
+const PROMPT_FILE_SUFFIX = '.md'
+const PACKAGE_DIRECTORY = find_package_directory(path.dirname(fileURLToPath(import.meta.url)))
+
+// An include that resolves to nothing is `undefined`, never an empty string, so a renamed heading
+// fails the whole composition rather than silently dropping a rule.
+function expand_line(line: string, rules: string): string | undefined {
+	const wanted = INCLUDE_PATTERN.exec(line)?.groups?.['wanted']
+
+	if (wanted === undefined) return line
+
+	return document_section.section(rules, wanted)?.text
+}
+
+function compose(lane_markdown: string, rules: string): string | undefined {
+	const expanded = lane_markdown.split('\n').map((line) => expand_line(line, rules))
+
+	if (expanded.includes(undefined)) return undefined
+
+	return expanded.join('\n')
+}
+
+// **Where the rules are: the checkout's `CLAUDE.md`, else the package copy it imports.** kit and a
+// consumer holding a full copy keep them in `CLAUDE.md`; a consumer written by `josh init` imports
+// them from the package, and its own `CLAUDE.md` — the bootstrap note and the project's additions —
+// stays loaded, because only the file the set was composed from is excluded.
+function rules_sources(cwd: string): ReadonlyArray<string> {
+	const imported = distributed_paths.CLAUDE_MD_IMPORT_LINE.replace(/^@/u, '')
+
+	return [path.join(cwd, RULES_FILE), path.join(cwd, imported)]
+}
+
+function composed_from(lane_markdown: string, rules_path: string): string | undefined {
+	const rules = document_section.read_optional(rules_path)
+
+	return rules === undefined ? undefined : compose(lane_markdown, rules)
+}
+
+function composed_set(cwd: string, package_directory: string): LaneSet | undefined {
+	const lane_markdown = document_section.read_optional(path.join(package_directory, LANE_DOCUMENT))
+
+	if (lane_markdown === undefined) return undefined
+
+	for (const rules_path of rules_sources(cwd)) {
+		const text = composed_from(lane_markdown, rules_path)
+
+		if (text !== undefined) return { text, rules_path }
+	}
+
+	return undefined
+}
+
+function composed_in(
+	cwd: string,
+	package_directory: string = PACKAGE_DIRECTORY,
+): string | undefined {
+	return composed_set(cwd, package_directory)?.text
+}
+
+// Named by its content and this account, so concurrent launches of the same text share one file and a
+// changed `CLAUDE.md` never reuses a stale one. The name is predictable in a temp directory other
+// accounts may write to, so an existing file is reused only when it is this account's own regular file
+// holding exactly this text; anything else is replaced through `stamp_file`, which refuses another
+// account's file and renames a new one into place whole. A file rather than the text itself, because
+// the launcher refuses a line break in any argv element but the prompt.
+function written(text: string): string | undefined {
+	const file_path = stamp_file.stamp_path(PROMPT_FILE_PREFIX, text, PROMPT_FILE_SUFFIX)
+
+	if (stamp_file.read_stamp_text(file_path) === text) return file_path
+
+	try {
+		return stamp_file.replace_text_stamp(file_path, text)
+	} catch {
+		return undefined
+	}
+}
+
+function excluded_settings(rules_path: string, cwd: string): string {
+	return JSON.stringify({ claudeMdExcludes: [rules_path, path.join(cwd, POINTER_FILE)] })
+}
+
+// No flags when the set cannot be composed or safely written: the child then loads `CLAUDE.md` as
+// before, which costs tokens but never loses a rule.
+function flags(cwd: string = process.cwd()): ReadonlyArray<string> {
+	const set = composed_set(cwd, PACKAGE_DIRECTORY)
+	const prompt_file = set === undefined ? undefined : written(set.text)
+
+	if (set === undefined || prompt_file === undefined) return []
+
+	return [PROMPT_FILE_FLAG, prompt_file, SETTINGS_FLAG, excluded_settings(set.rules_path, cwd)]
+}
+
+function tokens_of(text: string): string {
+	return cost_tokens.estimate(text).toLocaleString('en-US')
+}
+
+// `read:set lane-child`'s resident line: what each lane request carries in place of the rules file.
+function rules_tokens(rules_path: string): string {
+	return tokens_of(document_section.read_optional(rules_path) ?? '')
+}
+
+function resident_line(cwd: string = process.cwd()): string {
+	const set = composed_set(cwd, PACKAGE_DIRECTORY)
+	const rules = rules_tokens(set?.rules_path ?? path.join(cwd, RULES_FILE))
+	const lane_tokens = set === undefined ? 'not composed' : `${tokens_of(set.text)} tok`
+
+	return `  resident: lane instructions ${lane_tokens} in place of ${RULES_FILE} ${rules} tok`
+}
+
+const lane_instructions = {
+	PROMPT_FILE_FLAG,
+	SETTINGS_FLAG,
+	compose,
+	composed_in,
+	flags,
+	resident_line,
+}
+
+export { lane_instructions }

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

@@ -157,8 +157,7 @@ function build_input(values: ParsedValues, now_ms: number): BudgetInput | undefi
 
 	const started_at_ms = to_time_ms(cli_flags.string_of(values.started))
 
-	if (started_at_ms === undefined) return undefined
-	if (!are_values_readable(values)) return undefined
+	if (started_at_ms === undefined || !are_values_readable(values)) return undefined
 
 	return input_of(values, { answer, now_ms, started_at_ms })
 }

package/scripts/backlog/backlog-budget.ts

@@ -42,7 +42,7 @@ const WATCH_VERDICT = 'watch'
 const STOP_VERDICT = 'stop'
 const TRIAGE_VERDICT = 'triage'
 
-// `run` — start what `backlog:next` offered. `watch` — sleep the polling interval and ask again,
+// `run` — start what `backlog:next` offered. `watch` — sleep the re-ask floor and ask again,
 // except while something of the run's own is in flight, where the wake is the progress watcher's exit
 // and the interval is only a floor (`docs/maintainers/backlogrun-driver.md` → "Waiting while
 // something is in flight").
@@ -87,7 +87,7 @@ interface BudgetDecision {
 }
 
 const BLOCKED_REASON =
-	'Everything opted in is blocked or already running, so waiting can still change the answer. Poll again at the polling interval.'
+	'Everything opted in is blocked or already running, so waiting can still change the answer. Ask again at the re-ask floor (60 s).'
 
 const TRIAGE_REASON =
 	'An opted-in candidate carries neither `run:solo` nor `run:lane`, so nothing starts until it is judged. Read each issue named above, record its order and one of the two labels with a comment, then ask again.'
@@ -121,7 +121,7 @@ function max_reached_reason(merged: number, max_issues: number): string {
 }
 
 function draining_reason(running: number, reason: string): string {
-	return `Start nothing more and poll until the running children merge (running: ${String(running)}). Then report and finish — ${reason}`
+	return `Start nothing more and wait on \`pnpm josh lane:await\` until the running children merge (running: ${String(running)}). Then report and finish — ${reason}`
 }
 
 function idle_expired_reason(answer: BacklogAnswer, idle_budget_ms: number): string {
@@ -140,7 +140,7 @@ function idle_watch_reason(answer: BacklogAnswer, left_ms: number): string {
 // **The watch runs down while they drain, and restarts at each one collected.** A collected child is
 // work, so it moves `active_at`; an ask that offered nothing never does.
 function running_watch_reason(answer: BacklogAnswer, running: number, left_ms: number): string {
-	return `${waiting_on(answer)} and the idle watch has about ${to_minutes(left_ms)} minutes left, with ${String(running)} still running. Keep the working tree until they merge and poll at the polling interval — the watch is running down meanwhile.`
+	return `${waiting_on(answer)} and the idle watch has about ${to_minutes(left_ms)} minutes left, with ${String(running)} still running. Keep the working tree and wait on \`pnpm josh lane:await\` until they merge — the watch is running down meanwhile.`
 }
 
 function watching_reason(input: BudgetInput, left_ms: number): string {

package/scripts/backlog/backlog-drive-carried.ts

@@ -0,0 +1,26 @@
+import { has_label_name, IN_PROGRESS_LABEL } from '#scripts/issue/issue-labels'
+import { issue_state_cli } from '#scripts/issue/issue-state-cli'
+import type { LaneInfo } from '#scripts/lane/lane-registry'
+
+// The open lanes an earlier invocation dispatched that still claim their issue: `in-progress`, and not
+// stopped for a person's review. Their unit may have died across the hand-off, so the drive collects
+// them; a lane parked or held for review is a person's and is left alone.
+
+async function is_claimed(issue: string): Promise<boolean> {
+	const read = await issue_state_cli.read_issue(issue)
+
+	if (read.kind !== 'state') return false
+
+	return has_label_name(read.state.labels, IN_PROGRESS_LABEL) && !read.state.is_human_review
+}
+
+async function carried(lanes: ReadonlyArray<LaneInfo>): Promise<ReadonlyArray<string>> {
+	const dispatched = lanes.filter((lane) => lane.output !== undefined).map((lane) => lane.issue)
+	const claims = await Promise.all(dispatched.map(async (issue) => await is_claimed(issue)))
+
+	return dispatched.filter((_issue, index) => claims[index] === true)
+}
+
+const backlog_drive_carried = { carried }
+
+export { backlog_drive_carried }

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

@@ -6,7 +6,7 @@ import { issue_cite } from '#scripts/issue/issue-cite'
 import { hook_decision } from '#scripts/josh/hook-decision'
 import { josh_command } from '#scripts/josh/josh-run'
 import { lane_await, type AwaitState } from '#scripts/lane/lane-await'
-import { lane_registry } from '#scripts/lane/lane-registry'
+import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
 import { lane_sampler } from '#scripts/lane/lane-sampler'
 import { error_text } from '#scripts/lib/error-message'
 import { json_value } from '#scripts/lib/json-value'
@@ -24,6 +24,7 @@ import {
 	type OfferRead,
 } from './backlog-drive'
 import { backlog_drive_args, type DriveContext } from './backlog-drive-args'
+import { backlog_drive_carried } from './backlog-drive-carried'
 import { backlog_drive_finish } from './backlog-drive-finish'
 import { backlog_drive_launch } from './backlog-drive-launch'
 import { backlog_drive_named } from './backlog-drive-named'
@@ -32,6 +33,7 @@ import { backlog_drive_offer_argv } from './backlog-drive-offer-argv'
 import { backlog_drive_owner } from './backlog-drive-owner'
 import { backlog_drive_restore } from './backlog-drive-restore'
 import { backlog_drive_retrospective } from './backlog-drive-retrospective'
+import { backlog_drive_seats } from './backlog-drive-seats'
 import { backlog_offer_cli } from './backlog-offer-cli'
 import { backlog_ready } from './backlog-ready'
 
@@ -153,10 +155,10 @@ function finished_checker(seeded: ReadonlyArray<string>): (issue: string) => boo
 	}
 }
 
-async function open_lanes(): Promise<ReadonlyArray<string>> {
+async function open_lanes(): Promise<ReadonlyArray<LaneInfo>> {
 	const lanes = await lane_registry.list_lanes()
 
-	return lanes.filter((lane) => !lane.is_stranded).map((lane) => lane.issue)
+	return lanes.filter((lane) => !lane.is_stranded)
 }
 
 function end_line(end: DriveEnd): string {
@@ -190,6 +192,7 @@ function ports_of(
 		offer: async (state) => await read_offer(state, context),
 		launch: async (issue) => await backlog_drive_launch.launch(issue, context.owner),
 		free_lanes: backlog_ready.drive_free_lane_count,
+		has_lane: backlog_drive_seats.has_kept_lane,
 		judgement_owed: judgement_reader(),
 		now: () => new Date(),
 		sleep: async (milliseconds) => {
@@ -211,9 +214,11 @@ async function seeded_lanes(context: DriveContext): Promise<ReadonlyArray<string
 
 	await backlog_drive_named.reconcile(carry, events, context.owner)
 
-	const lanes = [...new Set([...(await open_lanes()), ...context.awaited])]
+	const open = await open_lanes()
+	const lanes = [...new Set([...open.map((lane) => lane.issue), ...context.awaited])]
+	const dispatched = await backlog_drive_carried.carried(open)
 
-	return backlog_drive_restore.restore(lanes, events, carry.merged_issues ?? [])
+	return backlog_drive_restore.restore(lanes, events, carry.merged_issues ?? [], dispatched)
 }
 
 // The interval between two asks is `backlog:budget`'s own, so the driver keeps the one its reason prints.

package/scripts/backlog/backlog-drive-named.ts

@@ -1,5 +1,4 @@
-import { has_label_name, NEEDS_DECISION_LABEL } from '#scripts/issue/issue-labels'
-import { issue_state_cli } from '#scripts/issue/issue-state-cli'
+import { lane_parked } from '#scripts/lane/lane-parked'
 import { run_carry, type RunCarry } from '#scripts/run/carry/run-carry'
 import type { RunEvent } from '#scripts/run/event/run-event-stream'
 import type { MergeResult } from '#scripts/run/merge/run-merge-cli'
@@ -13,7 +12,7 @@ const { MERGE_TOKEN } = run_merge_token
 
 const NO_RETRIES = 0
 const FIRST = 0
-const TERMINAL_OUTCOMES: ReadonlySet<string> = new Set(['merged', 'parked', 'split'])
+const TERMINAL_OUTCOMES: ReadonlySet<string> = new Set(['merged', 'parked', 'split', 'withdrawn'])
 
 // The skip follows the declared order alone: an issue `run:add` put in was
 // asked for on its own, so its failure skips nothing and a declared failure does not skip it.
@@ -98,9 +97,8 @@ function skip_after_failure(target: string, issue: string, owner: string): void
 async function should_skip(issue: string, outcome: MergeResult['outcome']): Promise<boolean> {
 	if (outcome === 'failed') return true
 	if (outcome !== 'parked') return false
-	const read = await issue_state_cli.read_issue(issue)
 
-	return read.kind === 'state' && has_label_name(read.state.labels, NEEDS_DECISION_LABEL)
+	return await lane_parked.is_parked(issue)
 }
 
 async function mark_done(issue: string, result: MergeResult, owner: string): Promise<void> {

package/scripts/backlog/backlog-drive-restore.ts

@@ -5,12 +5,14 @@ const SETTLED_KINDS: ReadonlySet<string> = new Set([
 	run_event_stream.EVENT_KIND.MERGE,
 	run_event_stream.EVENT_KIND.PARK,
 	run_event_stream.EVENT_KIND.SPLIT,
+	run_event_stream.EVENT_KIND.WITHDRAW,
 	run_event_stream.EVENT_KIND.OUTAGE,
 ])
 const DONE_KINDS: ReadonlySet<string> = new Set([
 	run_event_stream.EVENT_KIND.MERGE,
 	run_event_stream.EVENT_KIND.PARK,
 	run_event_stream.EVENT_KIND.SPLIT,
+	run_event_stream.EVENT_KIND.WITHDRAW,
 ])
 
 function issue_of(event: RunEvent): string | undefined {
@@ -54,14 +56,38 @@ function parked_issues(events: ReadonlyArray<RunEvent>): ReadonlySet<number> {
 	)
 }
 
+// The issues this invocation launched or settled — any other dispatched lane was carried in from an
+// earlier invocation.
+function mentioned_issues(events: ReadonlyArray<RunEvent>): ReadonlySet<string> {
+	const tracked = events.filter(
+		(event) =>
+			event.kind === run_event_stream.EVENT_KIND.CHILD_LAUNCH || SETTLED_KINDS.has(event.kind),
+	)
+
+	return new Set(tracked.map((event) => issue_of(event)).filter((issue) => issue !== undefined))
+}
+
+// The lanes still in flight: launched by this invocation and not settled, or dispatched by an earlier
+// one and never seen by this one — a lane nobody collects otherwise waits forever.
 function restore(
 	lanes: ReadonlyArray<string>,
 	events: ReadonlyArray<RunEvent>,
 	merged_issues: ReadonlyArray<number>,
+	dispatched: ReadonlyArray<string> = [],
 ): ReadonlyArray<string> {
 	const active = active_issues(events)
+	const mentioned = mentioned_issues(events)
+	const carried = new Set(dispatched.filter((issue) => !mentioned.has(issue)))
 
-	return lanes.filter((issue) => active.has(issue) && !merged_issues.includes(Number(issue)))
+	return lanes.filter(
+		(issue) => (active.has(issue) || carried.has(issue)) && !merged_issues.includes(Number(issue)),
+	)
 }
 
-export const backlog_drive_restore = { active_issues, restore, settled_issues, parked_issues }
+export const backlog_drive_restore = {
+	active_issues,
+	mentioned_issues,
+	restore,
+	settled_issues,
+	parked_issues,
+}

package/scripts/backlog/backlog-drive-seats.ts

@@ -0,0 +1,27 @@
+import { lane_registry } from '#scripts/lane/lane-registry'
+import type { DrivePorts } from './backlog-drive'
+
+type SeatPorts = Pick<DrivePorts, 'free_lanes' | 'has_lane'>
+
+// The issues a pass launches: every one that already holds a kept lane, which it reuses, then as many
+// of the rest as there are free lanes.
+async function seated(issues: ReadonlyArray<string>, ports: SeatPorts): Promise<Array<string>> {
+	const kept = await Promise.all(issues.map(async (issue) => await ports.has_lane(issue)))
+	const fresh = issues.filter((_issue, index) => kept[index] !== true)
+
+	return [
+		...issues.filter((_issue, index) => kept[index] === true),
+		...fresh.slice(0, await ports.free_lanes()),
+	]
+}
+
+// A kept lane is one a child was dispatched into — `lane:launch` reuses it rather than opening one.
+async function has_kept_lane(issue: string): Promise<boolean> {
+	const lane = await lane_registry.find_open_lane(issue)
+
+	return lane?.output !== undefined
+}
+
+const backlog_drive_seats = { has_kept_lane, seated }
+
+export { backlog_drive_seats }

package/scripts/backlog/backlog-drive.ts

@@ -20,6 +20,7 @@ import { issue_cite } from '#scripts/issue/issue-cite'
 import type { LaunchOutcome } from '#scripts/lane/lane-launch-cli'
 import type { MergeResult } from '#scripts/run/merge/run-merge-cli'
 import { run_merge_token, type MergeToken } from '#scripts/run/merge/run-merge-token'
+import { backlog_drive_seats } from './backlog-drive-seats'
 
 const { MERGE_TOKEN } = run_merge_token
 const RUN_VERDICT = 'run'
@@ -124,6 +125,9 @@ interface DrivePorts {
 	// The lanes free right now — `backlog_ready.drive_free_lane_count` in production, the limit less the
 	// open lanes.
 	free_lanes: () => Promise<number>
+	// Whether the issue already holds a kept lane (one a child was dispatched into) — it is reused, so it
+	// takes no free seat.
+	has_lane: (issue: string) => Promise<boolean>
 	// How many open issues lacking `auto-ok` still owe a judgement — `auto_ok_judge_read.owed` in
 	// production, `0` when the read failed.
 	judgement_owed: () => Promise<number>
@@ -265,10 +269,10 @@ async function refused(
 	return ended('launch', state, undefined, issue)
 }
 
-// **No more launches than free lanes**. `backlog:offer` lists every ready issue
-// without reading the lanes, so launching all of them overran `JOSH_LANE_LIMIT` until `lane:open` ran
-// out of seats. The free count is read once, before the first launch, because every launch here opens
-// a lane the count would otherwise have to be told about.
+// **No more new lanes than free lanes**. `backlog:offer` lists every ready issue without reading the
+// lanes, so launching all of them overran `JOSH_LANE_LIMIT` until `lane:open` ran out of seats. An issue
+// that already holds a kept lane reuses it and takes no seat (`backlog-drive-seats.ts`); the rest launch
+// up to the free count, read once before the first launch.
 //
 // **Only a launch is activity**: a pass that started nothing — every lane taken
 // — keeps `active` where it was, or the once-a-minute offer would restart the idle budget for good.
@@ -284,9 +288,10 @@ async function launch_all(
 	ports: DrivePorts,
 ): Promise<PassResult> {
 	const in_flight = [...state.in_flight]
-	const free = await ports.free_lanes()
 
-	for (const issue of issues.slice(0, free)) {
+	const launching = await backlog_drive_seats.seated(issues, ports)
+
+	for (const issue of launching) {
 		// eslint-disable-next-line no-await-in-loop -- lanes launch in order and the first refusal ends the pass
 		const outcome = await ports.launch(issue)
 

package/scripts/backlog/backlog-occupied.ts

@@ -0,0 +1,56 @@
+import type { LaneInfo } from '#scripts/lane/lane-registry'
+import type { RunEvent } from '#scripts/run/event/run-event-stream'
+import { run_invocation } from '#scripts/run/run-invocation'
+import { backlog_drive_restore } from './backlog-drive-restore'
+
+// The open lanes that hold a place under the lane limit — the one count `lane:limit`, the drive and
+// `run:board` all subtract from it.
+//
+// **A lane nobody will come back to holds no place.** A `--only` run works its named list and never
+// touches another lane, so a lane an earlier run left with no child in it would fill the limit for the
+// whole run, and the run's own issues would wait on it for good (joshuafolkken/kit#3967). Under a `--only`
+// run such a lane is not counted; its tree and branch stay, for the next run that names its issue.
+//
+// **Everything else keeps its place, so the count errs toward fewer free lanes.** A run that drains
+// the pool may offer any open lane's issue again, a lane whose child still works is busy whoever owns
+// it, and with no run there is nobody to judge ownership for. The read stays local — no issue label is
+// read — because the count gates the network read behind it (`backlog-ready.ts`).
+
+interface OccupiedRead {
+	// The live run's invocation, `undefined` when no run is live here.
+	invocation: string | undefined
+	// The live run's own events, for the issues it launched or settled; `undefined` where its scope
+	// could not be told, which leaves every open lane counted.
+	events: ReadonlyArray<RunEvent> | undefined
+	// The issues whose lane has no child working in it; read only for a `--only` run.
+	idle: (lanes: ReadonlyArray<LaneInfo>) => ReadonlyArray<string>
+}
+
+// The issues a `--only` run owns — those it names and those it launched or settled — or `undefined`
+// where there is no such run, or its events could not be scoped to it.
+function owned_issues(read: OccupiedRead): ReadonlySet<string> | undefined {
+	const { invocation, events } = read
+	const is_only = invocation !== undefined && run_invocation.has_only(invocation)
+
+	if (!is_only || events === undefined) return undefined
+
+	const named = (run_invocation.issue_numbers(invocation) ?? []).map(String)
+
+	return new Set([...named, ...backlog_drive_restore.mentioned_issues(events)])
+}
+
+function occupied_lanes(lanes: ReadonlyArray<LaneInfo>, read: OccupiedRead): Array<LaneInfo> {
+	const live = lanes.filter((lane) => !lane.is_stranded)
+	const owned = owned_issues(read)
+
+	if (owned === undefined) return live
+
+	const idle = new Set(read.idle(live))
+
+	return live.filter((lane) => owned.has(lane.issue) || !idle.has(lane.issue))
+}
+
+const backlog_occupied = { occupied_lanes }
+
+export { backlog_occupied }
+export type { OccupiedRead }