@joshuafolkken/kit 1.3044.0 → 1.3092.0

package/scripts/issue/issue-sample-prime.ts

@@ -6,6 +6,7 @@ import { git_gh_pr_too_large } from '#scripts/gh/git-gh-pr-too-large'
 import { git_closes_keyword } from '#scripts/git/git-closes-keyword'
 import { lane_ledger, type MergeEntry } from '#scripts/lane/lane-ledger'
 import { issue_closing_pr } from './issue-closing-pr'
+import { issue_observation_prime } from './issue-observation-prime'
 import {
 	issue_sample_gate,
 	type Condition,
@@ -105,6 +106,7 @@ async function prime(
 	bodies: ReadonlyArray<string | undefined>,
 	ports: PrimePorts = DEFAULT_PORTS,
 ): Promise<void> {
+	await issue_observation_prime.prime(bodies)
 	const unread = issue_sample_gate.unread_of(bodies)
 
 	if (unread.length === 0) return

package/scripts/issue/issue-search-count.ts

@@ -0,0 +1,26 @@
+import { git_gh_exec } from '#scripts/gh/git-gh-exec'
+import { parse_json } from '#scripts/git/parse-json-array'
+import { z } from 'zod'
+
+const count_schema = z.object({
+	total_count: z.number().int().nonnegative(),
+	incomplete_results: z.literal(false),
+})
+
+// Only for a query that expresses the entire classification in its qualifiers. Body-based
+// classification still needs the listing. Incomplete counts are unread, never a trusted rate.
+async function count(query: string): Promise<number | undefined> {
+	const parameters = new URLSearchParams({ q: query, per_page: '1' })
+
+	try {
+		const raw = await git_gh_exec.exec_gh_api({ path: `search/issues?${parameters.toString()}` })
+
+		return parse_json.parse_json_object_or_undefined(raw, count_schema)?.total_count
+	} catch {
+		return undefined
+	}
+}
+
+const issue_search_count = { count }
+
+export { issue_search_count }

package/scripts/issue/issue-search.ts

@@ -17,6 +17,27 @@ const SEARCH_RESULT_CEILING = 1000
 // is sized for the core REST budget: the search endpoint's own budget is the narrower one, so a
 // search does not spend it in one burst while other `gh` reads hold the remaining slots.
 const PAGE_CONCURRENCY = 4
+const WINDOW_READ_LIMIT = 15
+const MS_PER_SECOND = 1000
+const MS_PER_DAY = 86_400_000
+const SPLIT_DIVISOR = 2
+
+interface SearchWindow {
+	query: string
+	qualifier: string
+	start: number
+	end: number
+	is_open: boolean
+}
+
+type WindowReader = (
+	window: SearchWindow,
+	budget: { remaining: number },
+) => Promise<SearchResult | undefined>
+
+function skips_pages(first: SearchPage, should_split: boolean): boolean {
+	return should_split && first.total_count > SEARCH_RESULT_CEILING
+}
 
 const search_item_schema = z.object({
 	number: z.number().optional(),
@@ -72,10 +93,14 @@ async function read_page(query: string, page: number): Promise<SearchPage | unde
 // Every page of one search. Not `gh api --paginate`: it follows each page's `next` link one page
 // after another, at about 1.5 s a page. The first page names the total, so the rest are fetched
 // together; any page that does not read fails the whole search.
-async function read_pages(query: string): Promise<ReadonlyArray<SearchPage> | undefined> {
+async function read_pages(
+	query: string,
+	should_split = false,
+): Promise<ReadonlyArray<SearchPage> | undefined> {
 	const first = await read_page(query, FIRST_PAGE)
 
 	if (first === undefined) return undefined
+	if (skips_pages(first, should_split)) return [first]
 
 	const rest_numbers = Array.from(
 		{ length: Math.max(page_count(first) - FIRST_PAGE, 0) },
@@ -106,8 +131,80 @@ function to_result(pages: ReadonlyArray<SearchPage>): SearchResult {
 	// handed back — a window past that ceiling is measured on part of itself.
 	const total = pages[0]?.total_count ?? 0
 	const is_incomplete = pages.some((page) => page.incomplete_results)
+	const numbers = issues.map((issue) => issue.number).filter((number) => number > 0)
+	const has_duplicates = new Set(numbers).size !== numbers.length
+
+	return { issues, is_capped: is_incomplete || total !== issues.length || has_duplicates }
+}
+
+function window_query(window: SearchWindow): string {
+	const original_start = Date.parse(window.qualifier.split('>=').at(-1) ?? '')
+
+	if (window.is_open && window.start === original_start) return window.query
+
+	const start = new Date(window.start).toISOString().replace('.000Z', 'Z')
+	const end = new Date(window.end - MS_PER_SECOND).toISOString().replace('.000Z', 'Z')
+	const range = window.is_open ? `>=${start}` : `${start}..${end}`
+
+	return window.query.replace(
+		window.qualifier,
+		() => `${window.qualifier.split(':', 1)[0] ?? ''}:${range}`,
+	)
+}
+
+function merge_windows(results: ReadonlyArray<SearchResult>, total: number): SearchResult {
+	const issues = results.flatMap((result) => result.issues)
+	const unique = new Map(issues.map((issue) => [issue.number, issue]))
+	const is_capped =
+		results.some((result) => result.is_capped) ||
+		unique.size !== total ||
+		unique.size !== issues.length
+
+	return { issues: [...unique.values()], is_capped }
+}
 
-	return { issues, is_capped: is_incomplete || total > issues.length }
+async function split_window(
+	window: SearchWindow,
+	budget: { remaining: number },
+	total: number,
+	read: WindowReader,
+): Promise<SearchResult | undefined> {
+	const middle =
+		Math.floor((window.start + window.end) / SPLIT_DIVISOR / MS_PER_SECOND) * MS_PER_SECOND
+	const left = await read({ ...window, end: middle, is_open: false }, budget)
+
+	if (left === undefined) return undefined
+
+	const right = await read({ ...window, start: middle }, budget)
+
+	return right === undefined ? undefined : merge_windows([left, right], total)
+}
+
+function can_split(first: SearchPage, window: SearchWindow): boolean {
+	return (
+		!first.incomplete_results &&
+		first.total_count > SEARCH_RESULT_CEILING &&
+		window.end - window.start > MS_PER_SECOND
+	)
+}
+
+async function read_window(
+	window: SearchWindow,
+	budget: { remaining: number },
+): Promise<SearchResult | undefined> {
+	if (budget.remaining === 0) return { issues: [], is_capped: true }
+
+	budget.remaining -= 1
+	const pages = await read_pages(window_query(window), true)
+
+	if (pages === undefined) return undefined
+
+	const result = to_result(pages)
+	const [first] = pages
+
+	if (first === undefined || !can_split(first, window)) return result
+
+	return await split_window(window, budget, first.total_count, read_window)
 }
 
 // The search's issues, or `undefined` when any page could not be read.
@@ -121,7 +218,35 @@ async function search(query: string): Promise<SearchResult | undefined> {
 	}
 }
 
-const issue_search = { search, search_path }
+// The final interval stays open: the partition's union is the original lower-bounded query,
+// including timestamps ahead of this process. Never retry an incomplete or failed response.
+function rate_qualifier(query: string): string | undefined {
+	return /\b(?:created|closed):>=\d{4}-\d{2}-\d{2}\b/u.exec(query)?.[0]
+}
+
+async function search_complete(
+	query: string,
+	now_ms: number = Date.now(),
+): Promise<SearchResult | undefined> {
+	const qualifier = rate_qualifier(query)
+
+	if (qualifier === undefined) return await search(query)
+
+	const start = Date.parse(qualifier.split('>=').at(-1) ?? '')
+	const now = (Math.floor(now_ms / MS_PER_DAY) + 1) * MS_PER_DAY
+	const end = Math.max(now, start + MS_PER_SECOND)
+
+	try {
+		return await read_window(
+			{ query, qualifier, start, end, is_open: true },
+			{ remaining: WINDOW_READ_LIMIT },
+		)
+	} catch {
+		return undefined
+	}
+}
+
+const issue_search = { search, search_complete, search_path }
 
 export type { SearchIssue, SearchResult }
 export { issue_search }

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

@@ -220,6 +220,10 @@ async function placed(issue: SpillIssue, follow_up: number): Promise<number> {
 async function place(issue: SpillIssue, follow_up: number): Promise<number> {
 	const exit_code = await placed(issue, follow_up)
 
+	console.info(
+		`Prepared ${session_cite.issue(follow_up)} stays unpublished: record its plan with issue:plan --planned --no-notify, then run pnpm josh issue:file --publish <E> after placement succeeds.`,
+	)
+
 	if (exit_code !== SUCCESS_EXIT_CODE) {
 		console.error(
 			`✖ ${session_cite.issue(follow_up)} was not placed — place it with \`pnpm josh epic --add <E> ${String(follow_up)} --after ${String(issue.issue_number)}\`.`,

package/scripts/issue/upstream-interrupt-cli.ts

@@ -41,7 +41,7 @@ const RECOMMENDED = 'Wait for the upstream fix'
 const NOTIFY_COMMAND = 'pnpm josh notify --task-type confirmation'
 const ALTERNATIVES = ['Defer the upstream issue and resume the finder now']
 
-interface Interrupt {
+interface ParsedInterrupt {
 	finder: string
 	title: string
 	repo: string
@@ -49,6 +49,10 @@ interface Interrupt {
 	is_blocking_finder: boolean
 }
 
+interface Interrupt extends ParsedInterrupt {
+	finder_repo: string
+}
+
 interface Positionals {
 	finder: string
 	title: string
@@ -64,7 +68,7 @@ function positionals_of(positionals: ReadonlyArray<string>): Positionals | undef
 	return is_shaped ? { finder, title } : undefined
 }
 
-function parse(argv: ReadonlyArray<string>): Interrupt | undefined {
+function parse(argv: ReadonlyArray<string>): ParsedInterrupt | undefined {
 	const parsed = cli_flags.arguments_of(argv, OPTIONS)
 
 	if (parsed === undefined) return undefined
@@ -197,11 +201,13 @@ async function kept_body(interrupt: Interrupt): Promise<Interrupt | undefined> {
 
 async function comment(interrupt: Interrupt, body: string): Promise<boolean> {
 	try {
-		console.info(`comment: ${await git_gh_command.issue_comment(interrupt.finder, body)}`)
+		const url = await git_gh_command.issue_comment(interrupt.finder, body, interrupt.finder_repo)
+
+		console.info(`comment: ${url}`)
 
 		return true
 	} catch (error) {
-		const rerun = `pnpm josh issue:comment ${interrupt.finder} --body-file ${await saved(body)}`
+		const rerun = `GH_REPO=${shell_quote.word(interrupt.finder_repo)} pnpm josh issue:comment ${interrupt.finder} --body-file ${await saved(body)}`
 
 		return stopped('comment', error_text.message_of(error), rerun)
 	}
@@ -272,7 +278,17 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 		return FAILURE_EXIT_CODE
 	}
 
-	return (await interrupt_by_party(interrupt)) ? SUCCESS_EXIT_CODE : FAILURE_EXIT_CODE
+	const finder_repo = await git_gh_command.repo_get_name_with_owner()
+
+	if (finder_repo === undefined) {
+		console.error('✖ upstream:interrupt stopped: the finder repository could not be resolved.')
+
+		return FAILURE_EXIT_CODE
+	}
+
+	return (await interrupt_by_party({ ...interrupt, finder_repo }))
+		? SUCCESS_EXIT_CODE
+		: FAILURE_EXIT_CODE
 }
 
 const upstream_interrupt_cli = { run }

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

@@ -512,7 +512,7 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 	'lane:stats': {
 		...MEASURE_ARGUMENTS,
 		description:
-			'Print period lane throughput, stage, stop (by failed CI check, longest first), check and machine-load statistics; --sinks shows stage totals, --over lane chains, --why cause groups above a net-minute threshold, and --pairs scoped pair runs',
+			'Print period lane throughput, stage, stop (by failed CI check, longest first), check, runnable-to-dispatch wait and machine-load statistics; --sinks shows stage totals, --over lane chains, --why cause groups above a net-minute threshold, and --pairs scoped pair runs',
 		category: 'AI tools',
 		reference: [
 			'(--period <days> | --since <instant>) [--limit <lane-limit> | --sinks [<minutes>] | --over <minutes> | --why <minutes> | --pairs]',

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

@@ -65,7 +65,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 	'lint:related': {
 		script: 'scripts/lint/lint-related.ts',
 		description:
-			'Check only the changed files with prettier and eslint, and in kit the source guard tests (whole tree on fallback)',
+			'Apply eslint fixes and prettier to the resolved scope, then check remaining errors and in kit the source guard tests (whole tree on fallback)',
 		category: 'Development',
 		reference: [FILE_ARGUMENTS, 'developer', ['processes']],
 		core_weight: core_weights.CORE_WEIGHTS.lint,

package/scripts/josh/josh-commands-issue-write.ts

@@ -293,6 +293,15 @@ const ISSUE_WRITE_COMMANDS: Record<string, CommandEntry> = {
 					names: ['--no-auto-ok'],
 					description: 'needs human judgement or a verified user prohibition; no `auto-ok`.',
 				},
+				{
+					names: ['--prepare'],
+					description: 'create an unpublished child; `--route split` implies this.',
+				},
+				{
+					names: ['--publish <E>'],
+					description:
+						"validate/publish epic E's prepared children; retry the same epic on failure.",
+				},
 				{
 					names: ['--release'],
 					description:

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

@@ -22,7 +22,7 @@ const RUN_COMMANDS: Record<string, CommandEntry> = {
 		// A `--halfrun-stop` / `--human-review-stop` / `--prrun-stop` sends the stop confirmation.
 		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
 		reference: [
-			'[<issue> [--fullrun | --halfrun-stop | --human-review-stop | --prrun-stop]] | --adopt <issue>',
+			'[<issue> [--fullrun | --halfrun-stop | --halfrun-round | --human-review-stop | --prrun-stop]] | --adopt <issue>',
 			'automation',
 			['files'],
 		],
@@ -44,6 +44,11 @@ const RUN_COMMANDS: Record<string, CommandEntry> = {
 					description:
 						'marks a `halfrun` stop for `run:entry` to adopt, and sends its `confirmation` Telegram; answers `e2e-owed` (exit 1) until `test:e2e` answered green on this tree.',
 				},
+				{
+					names: ['--halfrun-round'],
+					description:
+						"starts a `halfrun` fix round: re-opens the issue's stopped `halfrun` record as running, owned by this session; answers `busy` (exit 1) when the tree holds no such stop.",
+				},
 				{
 					names: ['--human-review-stop'],
 					description:

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

@@ -58,7 +58,7 @@ const SHIP_COMMANDS: Record<string, CommandEntry> = {
 			'Start test:pinned in the background, run the gate and, once it is green, write the /code-review brief to a file, printing its path (--join to join them; it stops on an unpinned change)',
 		category: 'AI tools',
 		reference: [
-			'[--code-only] [--unpinned-ok "<reason>"] | --join [--fixing] | --pinned | --push',
+			'[--code-only] [--unpinned-ok "<reason>"] | --join [--fixing] | --pinned | --push [<slots>]',
 			'automation',
 			['processes', 'files', 'git', 'network'],
 		],
@@ -86,11 +86,11 @@ const SHIP_COMMANDS: Record<string, CommandEntry> = {
 				},
 				{
 					arguments: '--pinned',
-					note: "read test:pinned alone (the ship's pre-detach reads it anyway); a lane child returns at once",
+					note: "collect a stopped ship's remaining verdicts before editing or retrying; a lane child waits only for this continuation",
 				},
 				{
-					arguments: '--push',
-					note: 'launched by a lane open: push and open the PR at a green gate',
+					arguments: '--push 2',
+					note: 'launched by a lane open: push and open the PR at a green gate, recording the review plan’s slot count on the ledger',
 				},
 			],
 		},
@@ -191,7 +191,7 @@ const SHIP_COMMANDS: Record<string, CommandEntry> = {
 				{
 					names: ['--review'],
 					description:
-						'runs round 1 beside the gate; after sync and round 1, an owed round 2 runs beside the gate and joins before the PR opens. A High or unfixed Medium stops the ship. A pre-detach `test:pinned` stop probes remaining hunks in the background for the next pre-detach.',
+						'runs round 1 beside the gate; after sync and round 1, an owed round 2 runs beside the gate and joins before the PR opens. A High or unfixed Medium stops the ship. After a pre-detach `test:pinned` stop, collect remaining verdicts with `pnpm josh run:review --pinned` before editing or retrying.',
 				},
 				{
 					names: ['--unpinned-ok <reason>'],

package/scripts/josh/josh-run.ts

@@ -1,3 +1,4 @@
+import { run_startup } from '#scripts/run/startup/run-startup'
 import { execa } from 'execa'
 
 // One captured `pnpm josh` subprocess. A composite command that collapses a
@@ -42,9 +43,11 @@ function extra_options(
 	timeout_ms: number | undefined,
 	environment: Readonly<Record<string, string>> | undefined,
 ): ExtraOptions {
+	const child_environment = { ...run_startup.environment(), ...environment }
+
 	return {
 		...(timeout_ms !== undefined && { timeout: timeout_ms }),
-		...(environment !== undefined && { env: environment }),
+		...(Object.keys(child_environment).length > 0 && { env: child_environment }),
 	}
 }
 
@@ -76,7 +79,7 @@ async function josh_run(
 }
 
 async function josh_run_at(args: ReadonlyArray<string>, cwd: string): Promise<JoshResult> {
-	return await run_with_options(args, false, { cwd })
+	return await run_with_options(args, false, { ...extra_options(undefined, undefined), cwd })
 }
 
 // A step whose failure ends the composite: its stderr, else its stdout, else the exit code is the

package/scripts/josh/shared-cache.ts

@@ -1,6 +1,7 @@
 import { git_common_directory } from '#scripts/git/git-common-directory'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
 import { json_value } from '#scripts/lib/json-value'
+import { run_startup } from '#scripts/run/startup/run-startup'
 import { z } from 'zod'
 import { stamp_file } from './stamp-file'
 
@@ -49,6 +50,12 @@ function read<T>(
 ): T | undefined {
 	const parsed = schema.safeParse(read_value(slot, key, now_ms))
 
+	run_startup.metric(
+		'cache',
+		parsed.success && parsed.data !== undefined ? 'hit' : 'miss',
+		`${slot.prefix}:${key}`,
+	)
+
 	return parsed.success ? parsed.data : undefined
 }
 
@@ -73,7 +80,15 @@ async function remember<T>(
 
 	if (cached !== undefined) return cached
 
-	const value = await compute()
+	const value = await run_startup.phase(
+		`cache fill ${request.slot.prefix}`,
+		async () => {
+			run_startup.metric('cache', 'fill', `${request.slot.prefix}:${request.key}`)
+
+			return await compute()
+		},
+		{ edge_of: (result) => (result === undefined ? 'failed' : 'done') },
+	)
 
 	if (value !== undefined) write(request.slot, request.key, value, now_ms)
 

package/scripts/lane/lane-await.ts

@@ -14,6 +14,8 @@ import {
 } from '#scripts/run/run-liveness'
 import { lane_child_invocation } from './lane-child-invocation'
 import { lane_handoff } from './lane-handoff'
+import { lane_process_table } from './lane-process-table'
+import { lane_reap } from './lane-reap'
 import { process_tools } from './process-tools'
 
 // Detached lane children are not harness-tracked processes, so their completion fires no
@@ -111,6 +113,18 @@ function is_process_running_default(issue: string): boolean {
 	return process_trace_default(issue) === PROCESS_ALIVE
 }
 
+// A repair requested inside its replacement worker must still refuse every other owner.
+async function other_process_trace(issue: string): Promise<ProcessTrace> {
+	if (lane_handoff.is_ship_running(issue, process.cwd())) return PROCESS_ALIVE
+	const rows = await lane_process_table.read_table()
+
+	if (!rows?.some((row) => row.pid === process.pid)) return PROCESS_UNKNOWN
+
+	return lane_reap.is_child_running(issue, lane_process_table.probes_of(rows))
+		? PROCESS_ALIVE
+		: PROCESS_NONE
+}
+
 function is_shipped_default(issue: string, since_ms: number): boolean {
 	return lane_handoff.is_ship_succeeded(issue, process.cwd(), since_ms)
 }
@@ -309,6 +323,7 @@ const lane_await = {
 	is_process_running_default,
 	is_shipped_default,
 	parse_arguments,
+	other_process_trace,
 	process_trace_default,
 	wait_for_any,
 }

package/scripts/lane/lane-cli.ts

@@ -12,6 +12,7 @@ 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'
+import { lane_dispatch_dependency } from './lane-dispatch-dependency'
 import { lane_occupancy } from './lane-occupancy'
 import { lane_open, type OpenOutcome } from './lane-open'
 import { lane_output, type ReadOutcome, type RecordOutcome } from './lane-output'
@@ -360,6 +361,7 @@ async function output_command(rest: ReadonlyArray<string>): Promise<number> {
 // write** — `is_worth_warning` is what decides, rather than this function reading the outcome's shape.
 async function report_dispatch(outcome: DispatchOutcome, issue: string): Promise<number> {
 	console.error(lane_dispatch.describe(outcome, issue))
+	if (outcome.kind === 'dependency-wait') return lane_dispatch_dependency.WAIT_EXIT_CODE
 
 	if (lane_dispatch.is_worth_warning(outcome)) await lane_dispatch.warn_of_problem(outcome, issue)
 

package/scripts/lane/lane-dispatch-dependency.ts

@@ -0,0 +1,102 @@
+import { performance } from 'node:perf_hooks'
+import { epic_cross_repo } from '#scripts/epic/epic-cross-repo'
+import type { EpicChild } from '#scripts/epic/epic-graph'
+import { epic_live } from '#scripts/epic/epic-live'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { issue_not_before } from '#scripts/issue/issue-not-before'
+import { issue_publication_state } from '#scripts/issue/issue-publication-state'
+import { issue_sample_prime } from '#scripts/issue/issue-sample-prime'
+import { session_cite } from '#scripts/issue/session-cite'
+import { error_text } from '#scripts/lib/error-message'
+import { run_label } from '#scripts/run/run-label'
+import { lane_state } from './lane-state'
+import { lane_state_record } from './lane-state-record'
+
+const WAIT_EXIT_CODE = 75
+const WAIT_COMMAND = lane_state_record.DEPENDENCY_WAIT_COMMAND
+
+interface DependencyWait {
+	kind: 'dependency-wait'
+	reason: string
+}
+
+async function unresolved(child: EpicChild): Promise<Array<EpicChild>> {
+	const references = await epic_live.blockers(child.number, child.repo)
+	const blockers = await Promise.all(
+		references.map(async (reference) => await epic_live.child(reference.number, reference.repo)),
+	)
+
+	epic_cross_repo.reset_publish_cache()
+
+	return blockers.filter(
+		(blocker) => epic_cross_repo.resolve_cross_repo(blocker, child) !== 'resolved',
+	)
+}
+
+async function start_wait(child: EpicChild): Promise<string | undefined> {
+	if (issue_publication_state.is_pending(child.body)) return 'publication is pending'
+	if (child.state !== 'OPEN') return 'issue is no longer open'
+	await issue_sample_prime.prime([child.body])
+
+	return issue_not_before.waiting_reason(child.body)
+}
+
+async function reason_of(issue: string): Promise<string | undefined> {
+	const repo = await git_gh_command.repo_get_name_with_owner()
+	if (repo === undefined) throw new Error('Cannot resolve launch repository')
+	const child = await epic_live.child(Number(issue), repo)
+	const wait = await start_wait(child)
+	if (wait !== undefined) return wait
+	const blockers = await unresolved(child)
+	if (blockers.length === 0) return undefined
+
+	const names = blockers.map((blocker) =>
+		session_cite.issue(blocker.number, undefined, blocker.repo),
+	)
+
+	return `unfinished blockers: ${names.join(', ')}`
+}
+
+function waiting(issue: string, reason: string, started: number): DependencyWait {
+	const elapsed = Math.round(performance.now() - started)
+
+	console.error(`Lane ${session_cite.issue(issue)} waiting (${String(elapsed)} ms): ${reason}`)
+
+	return { kind: 'dependency-wait', reason }
+}
+
+// Called at each lane worker spawn, including resume generations. A failed read is a retryable wait.
+async function check(issue: string): Promise<DependencyWait | undefined> {
+	const started = performance.now()
+
+	try {
+		const reason = await reason_of(issue)
+		if (reason === undefined) return undefined
+
+		return waiting(issue, reason, started)
+	} catch (error) {
+		return waiting(issue, `unknown dependency state: ${error_text.message_of(error)}`, started)
+	}
+}
+
+async function defer(issue: string): Promise<void> {
+	await lane_state.record_change({ issue, state: 'paused', command: WAIT_COMMAND })
+	await run_label.unmark(issue)
+}
+
+async function deferred(issue: string): Promise<ReadonlyArray<string>> {
+	const state = await lane_state.read_state(issue)
+
+	return state?.changed_by === WAIT_COMMAND ? ['launch dependency confirmation'] : []
+}
+
+async function begin(issue: string): Promise<void> {
+	const waits = await deferred(issue)
+	if (waits.length === 0) return
+	await lane_state.record_change({ issue, state: 'running', command: 'lane:dispatch' })
+}
+
+const lane_dispatch_dependency = { check, defer, deferred, begin, WAIT_EXIT_CODE }
+
+export type { DependencyWait }
+export { lane_dispatch_dependency }