@joshuafolkken/kit 1.3044.0 → 1.3092.0

package/scripts/lane/lane-dispatch-wait-stats.ts

@@ -0,0 +1,239 @@
+import { backlog_hold_codes } from '#scripts/backlog/backlog-hold-codes'
+import { backlog_next_report } from '#scripts/backlog/backlog-next-report'
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { MS_PER_MINUTE } from '#scripts/lib/timeouts'
+import { run_event_filed } from '#scripts/run/event/run-event-filed'
+import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-stream'
+import { lane_ledger, type DispatchEntry, type LedgerEntry } from './lane-ledger'
+import type { OfferEntry } from './lane-ledger-schema-offer'
+import { lane_stage_stats } from './lane-stage-stats'
+import { lane_stats, type StatsWindow } from './lane-stats'
+
+// How long an issue ready to start waited for its dispatch (joshuafolkken/kit#7508): the owner's bound
+// is one minute from the moment it became runnable, and #7503's overrun was found only by matching logs
+// by hand. Printed by `josh lane:stats` as one row: the period's dispatches, the median and longest
+// wait, and how many passed the bound.
+//
+// **The wait starts at the runnable stretch the dispatch ended**: the offers since the issue's previous
+// dispatch, from the first one that saw it and held nothing back on it — or, when the issue was filed
+// after the last offer that could not start it, at that filing (the `filed` run event), since an offer
+// only reads it at the next pass. A dispatch no offer saw (a ledger from before `offer` entries, or a
+// lane opened by hand) is counted under `not measured`.
+//
+// **A seat that was not there is not waiting**: a hold by memory, a usage limit or the `run:solo` gate,
+// and the time after a `released` entry (every lane taken, or the run finished), each lasting until the
+// next `held`, `released` or `dispatch` entry as `lane-held-stats.ts` tiles them, are taken out.
+
+const { KIND } = lane_ledger
+const { MEMORY_REASON, REASON_SEPARATOR, USAGE_LIMIT_REASON } = backlog_hold_codes
+const { NOT_MEASURED, is_dispatch } = lane_stage_stats
+const RETRY_VERDICT = backlog_next_report.VERDICT_TOKENS.retry
+const LIMIT_MS = MS_PER_MINUTE
+const SEATLESS_REASONS: ReadonlySet<string> = new Set([MEMORY_REASON, USAGE_LIMIT_REASON])
+const SOLO_SUFFIX = `${REASON_SEPARATOR}solo`
+// A filing in this repository: one in another names its owner and repository before the `#`.
+const THIS_REPOSITORY_REFERENCE = /^#(?<issue>\d+)$/u
+const COLUMNS = [
+	'dispatch wait',
+	'dispatches',
+	'median (min)',
+	'max (min)',
+	'longest',
+	'over 1 min',
+	NOT_MEASURED,
+] as const
+const ROW_LABEL = 'runnable → dispatch'
+
+interface Span {
+	from_ms: number
+	to_ms: number
+}
+
+interface Stretch {
+	from_ms: number
+	after_ms: number
+}
+
+interface History {
+	offers: ReadonlyArray<OfferEntry>
+	since_ms: number
+}
+
+interface Wait {
+	issue: number
+	wait_ms: number
+}
+
+interface Records {
+	entries: ReadonlyArray<LedgerEntry>
+	seatless: ReadonlyArray<Span>
+	filed: ReadonlyMap<number, number>
+}
+
+function ms_of(entry: { at: string }): number {
+	return Date.parse(entry.at)
+}
+
+function is_offer(entry: LedgerEntry): entry is OfferEntry {
+	return entry.kind === KIND.OFFER
+}
+
+function is_runnable(offer: OfferEntry, issue: number): boolean {
+	return (
+		offer.seen.includes(issue) && offer.excluded.every((exclusion) => exclusion.issue !== issue)
+	)
+}
+
+function is_seat_end(entry: LedgerEntry): boolean {
+	return entry.kind === KIND.HELD || entry.kind === KIND.RELEASED || is_dispatch(entry)
+}
+
+function is_seatless(entry: LedgerEntry): boolean {
+	if (entry.kind === KIND.RELEASED) return true
+
+	return (
+		entry.kind === KIND.HELD &&
+		(SEATLESS_REASONS.has(entry.reason) || entry.reason.endsWith(SOLO_SUFFIX))
+	)
+}
+
+function seatless_spans(entries: ReadonlyArray<LedgerEntry>): Array<Span> {
+	const marks = entries.filter((entry) => is_seat_end(entry))
+
+	return marks.flatMap((mark, index) => {
+		const next = marks[index + 1]
+
+		return next !== undefined && is_seatless(mark)
+			? { from_ms: ms_of(mark), to_ms: ms_of(next) }
+			: []
+	})
+}
+
+// Each issue of this repository a run filed, at its first filing.
+function filed_reference(event: RunEvent): string {
+	if (event.kind !== run_event_stream.EVENT_KIND.FILED) return ''
+
+	return run_event_filed.parse(event.text)?.reference ?? ''
+}
+
+function filed_issue(event: RunEvent): number | undefined {
+	const issue = THIS_REPOSITORY_REFERENCE.exec(filed_reference(event))?.groups?.['issue']
+
+	return issue === undefined ? undefined : Number(issue)
+}
+
+// Each issue of this repository a run filed, at its first filing: the stream is oldest first, and a
+// `Map` keeps the last of a repeated key, so the pairs go in newest first.
+function filed_times(events: ReadonlyArray<RunEvent>): Map<number, number> {
+	const pairs = events.flatMap((event): Array<[number, number]> => {
+		const issue = filed_issue(event)
+
+		return issue === undefined ? [] : [[issue, ms_of(event)]]
+	})
+
+	return new Map(pairs.toReversed())
+}
+
+// A `retry` offer excludes only the issues it was asked to, so it says nothing about the rest.
+function is_decision(entry: LedgerEntry): entry is OfferEntry {
+	return is_offer(entry) && entry.verdict !== RETRY_VERDICT
+}
+
+// The offers since the issue's previous dispatch that decided on it, and when that dispatch was.
+function history_of(entries: ReadonlyArray<LedgerEntry>, index: number, issue: number): History {
+	const before = entries.slice(0, index)
+	const previous_index = before.findLastIndex(
+		(entry) => is_dispatch(entry) && entry.issue === issue,
+	)
+	const previous = before[previous_index]
+	const offers = before.slice(previous_index + 1).filter((entry) => is_decision(entry))
+
+	return { offers, since_ms: previous === undefined ? -Infinity : ms_of(previous) }
+}
+
+// A stretch with no offer holding the issue back starts after its previous dispatch at the earliest.
+function stretch_of(history: History, issue: number): Stretch | undefined {
+	const { offers, since_ms } = history
+	const blocked_index = offers.findLastIndex((offer) => !is_runnable(offer, issue))
+	const first = offers[blocked_index + 1]
+
+	if (first === undefined) return undefined
+
+	const blocked = offers[blocked_index]
+
+	return { from_ms: ms_of(first), after_ms: blocked === undefined ? since_ms : ms_of(blocked) }
+}
+
+// A filing between the last offer that could not start the issue and the stretch's first offer is when
+// it became runnable; the next pass only read it.
+function start_ms(stretch: Stretch, filed_ms: number | undefined): number {
+	if (filed_ms === undefined) return stretch.from_ms
+
+	return filed_ms > stretch.after_ms && filed_ms < stretch.from_ms ? filed_ms : stretch.from_ms
+}
+
+function overlap_ms(span: Span, from_ms: number, to_ms: number): number {
+	return Math.max(0, Math.min(span.to_ms, to_ms) - Math.max(span.from_ms, from_ms))
+}
+
+function wait_of(records: Records, dispatch: DispatchEntry, index: number): Wait | undefined {
+	const stretch = stretch_of(history_of(records.entries, index, dispatch.issue), dispatch.issue)
+
+	if (stretch === undefined) return undefined
+
+	const from_ms = start_ms(stretch, records.filed.get(dispatch.issue))
+	const to_ms = ms_of(dispatch)
+	const seatless = records.seatless
+		.map((span) => overlap_ms(span, from_ms, to_ms))
+		.reduce((sum, value) => sum + value, 0)
+
+	return { issue: dispatch.issue, wait_ms: to_ms - from_ms - seatless }
+}
+
+function longest_of(waits: ReadonlyArray<Wait>): Wait | undefined {
+	return waits.toSorted((left, right) => right.wait_ms - left.wait_ms)[0]
+}
+
+function row_of(waits: ReadonlyArray<Wait>, dispatches: number): string {
+	const values = waits.map((wait) => wait.wait_ms)
+	const longest = longest_of(waits)
+
+	return lane_stats.to_row([
+		ROW_LABEL,
+		String(dispatches),
+		lane_stage_stats.cell(lane_stats.median(values)),
+		lane_stage_stats.cell(longest?.wait_ms),
+		longest === undefined ? NOT_MEASURED : issue_cite.plain_for('terminal', longest.issue),
+		String(values.filter((value) => value > LIMIT_MS).length),
+		String(dispatches - waits.length),
+	])
+}
+
+// The period's table: `entries` and `events` are the whole ledger and run-event stream, so a dispatch
+// in the window finds the offers and the filing before it.
+function table(
+	entries: ReadonlyArray<LedgerEntry>,
+	window: StatsWindow,
+	events: ReadonlyArray<RunEvent> = [],
+): string {
+	const period = new Set(
+		lane_stats.in_window(
+			entries.filter((entry) => is_dispatch(entry)),
+			window,
+		),
+	)
+	const records = { entries, seatless: seatless_spans(entries), filed: filed_times(events) }
+	const waits = entries.flatMap((entry, index) =>
+		is_dispatch(entry) && period.has(entry) ? (wait_of(records, entry, index) ?? []) : [],
+	)
+
+	return [
+		lane_stats.to_row(COLUMNS),
+		lane_stats.to_row(COLUMNS.map(() => '---')),
+		row_of(waits, period.size),
+	].join('\n')
+}
+
+const lane_dispatch_wait_stats = { table }
+
+export { lane_dispatch_wait_stats }

package/scripts/lane/lane-dispatch.ts

@@ -11,12 +11,15 @@ 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_park } from '#scripts/run/park/run-park'
 import { run_label } from '#scripts/run/run-label'
+import { run_startup } from '#scripts/run/startup/run-startup'
 import { lane_child_invocation } from './lane-child-invocation'
 import { lane_child_marker } from './lane-child-marker'
+import { lane_dispatch_dependency, type DependencyWait } from './lane-dispatch-dependency'
 import { lane_dispatch_log } from './lane-dispatch-log'
 import { lane_dispatch_prepare } from './lane-dispatch-prepare'
 import { lane_ledger_write } from './lane-ledger-write'
 import { lane_output } from './lane-output'
+import { lane_reap } from './lane-reap'
 import { lane_registry, type LaneInfo } from './lane-registry'
 import { lane_seat_start } from './lane-seat-start'
 import { lane_state } from './lane-state'
@@ -50,6 +53,7 @@ const WARNING_RECOVERY =
 // once rather than inlined at each use.
 const LABEL_UNSET_KIND = 'label-unset'
 const RESTART_START = 'restart'
+const DEPENDENCY_WAIT = 'dependency-wait'
 
 interface Dispatched {
 	kind: 'dispatched'
@@ -71,6 +75,7 @@ interface Dispatched {
 
 type DispatchOutcome =
 	| Dispatched
+	| DependencyWait
 	| { kind: 'failed'; lane: LaneInfo; log_path: string; note: string }
 	| { kind: 'no-lane' }
 	| { kind: 'unrecordable'; reason: string }
@@ -236,6 +241,14 @@ async function dispatched_start(
 // again only once `needs-decision` is off, so a record still on disk is one a person cleared by hand on
 // GitHub, and left in place it would silence `lane-park` on this child's own stop
 // (joshuafolkken/kit#4132).
+function worker_environment(lane: LaneInfo): Record<string, string> {
+	return {
+		...lane_child_marker.env_for(lane.issue),
+		...lane_seat_start.environment(lane),
+		[run_startup.ENVIRONMENT_KEY]: '',
+	}
+}
+
 async function started(request: StartRequest): Promise<DispatchOutcome> {
 	const notes: Array<string> = []
 	const existing = existing_dispatch(request)
@@ -249,10 +262,7 @@ async function started(request: StartRequest): Promise<DispatchOutcome> {
 			cwd: request.lane.directory,
 			log_path: request.log_path,
 			profile: request.profile,
-			env: {
-				...lane_child_marker.env_for(request.lane.issue),
-				...lane_seat_start.environment(request.lane),
-			},
+			env: worker_environment(request.lane),
 		},
 		(note) => {
 			notes.push(note)
@@ -319,14 +329,34 @@ async function claimed(issue: string, start: DispatchStart): Promise<LabelWrite>
 	return await mark_in_progress(issue)
 }
 
+async function start_wait(
+	issue: string,
+	request: StartRequest,
+	start: DispatchStart,
+): Promise<DependencyWait | undefined> {
+	if (request.profile.provider !== 'openai' && lane_reap.is_child_running(issue)) {
+		return { kind: DEPENDENCY_WAIT, reason: 'child is already running' }
+	}
+
+	const wait = await lane_dispatch_dependency.check(issue)
+
+	if (wait !== undefined && start === RESTART_START) await lane_dispatch_dependency.defer(issue)
+
+	return wait
+}
+
 async function finish_dispatch(
 	issue: string,
 	request: StartRequest,
 	start: DispatchStart,
 ): Promise<DispatchOutcome> {
+	const wait = await start_wait(issue, request, start)
+	if (wait !== undefined) return wait
+
 	const mark = await claimed(issue, start)
 
 	if (!mark.is_applied) return { kind: LABEL_UNSET_KIND, reason: mark.reason }
+	await lane_dispatch_dependency.begin(issue)
 	const outcome = await started(request)
 
 	const is_failed = outcome.kind === 'failed'
@@ -396,7 +426,10 @@ function resume_sentence(outcome: Dispatched): string {
 
 // Never throws: it is reached from `warn_of_problem`, and a formatter that raised would lose the very
 // message the warning exists to carry — the pid among it, with the child already running.
-function describe(outcome: DispatchOutcome, issue: string): string {
+function describe_dispatch(
+	outcome: Exclude<DispatchOutcome, DependencyWait>,
+	issue: string,
+): string {
 	if (outcome.kind === 'no-lane') {
 		return `No lane is open for ${session_cite.issue(issue)}. Run \`pnpm josh lane:open ${issue}\` first, then dispatch into it.`
 	}
@@ -414,6 +447,10 @@ function describe(outcome: DispatchOutcome, issue: string): string {
 	return `Dispatched \`${outcome.invocation}\` as process ${String(outcome.pid)} in ${outcome.lane.directory} with ${agent_role_profile.describe(outcome.profile)}.${agent_role_profile.default_notice()}${resume_sentence(outcome)}${log_sentence(outcome, issue)}`
 }
 
+function describe(outcome: DispatchOutcome, issue: string): string {
+	return outcome.kind === DEPENDENCY_WAIT ? outcome.reason : describe_dispatch(outcome, issue)
+}
+
 /**
  * Whether this outcome is one nobody would otherwise hear about.
  *
@@ -422,6 +459,8 @@ function describe(outcome: DispatchOutcome, issue: string): string {
  * exit zero *silently*, leaving an operator to poll a file the launcher already said it could not open.
  */
 function is_worth_warning(outcome: DispatchOutcome): boolean {
+	if (outcome.kind === DEPENDENCY_WAIT) return false
+
 	return outcome.kind !== 'dispatched' || outcome.notes.length > 0
 }
 

package/scripts/lane/lane-early-push-count.ts

@@ -0,0 +1,21 @@
+import type { LedgerEntry } from './lane-ledger'
+
+// The ledger samples an observation wait can name (`issue-observation-gate.ts`), counted over every
+// early-push line (joshuafolkken/kit#7503). A line recorded before it carried `slots` never counts.
+const MULTI_SLOT_EARLY_PUSH = 'multi-slot-early-push'
+const PUSHED = 'pushed'
+const MULTI_SLOT_MINIMUM = 2
+
+// Early pushes that reached the remote from a round with more than one review slot.
+function multi_slot_pushed(entries: ReadonlyArray<LedgerEntry>): number {
+	return entries.filter(
+		(entry) =>
+			entry.kind === 'early-push' &&
+			entry.result === PUSHED &&
+			(entry.slots ?? 0) >= MULTI_SLOT_MINIMUM,
+	).length
+}
+
+const lane_early_push_count = { MULTI_SLOT_EARLY_PUSH, multi_slot_pushed }
+
+export { lane_early_push_count }

package/scripts/lane/lane-install.ts

@@ -3,6 +3,7 @@ import { core_budget } from '#scripts/gate/core-budget'
 import { buffered_process } from '#scripts/lib/buffered-process'
 import { PACKAGE_JSON, package_manifest } from '#scripts/lib/package-manifest'
 import { INSTALL_TIMEOUT_MS } from '#scripts/lib/timeouts'
+import { run_startup } from '#scripts/run/startup/run-startup'
 
 // Filling the lane, which is the other half of opening one.
 //
@@ -61,16 +62,25 @@ function has_manifest(directory: string): boolean {
  */
 async function install_dependencies(directory: string): Promise<InstallResult> {
 	if (!has_manifest(directory)) return { is_installed: true, output: NO_MANIFEST_OUTPUT }
+	const admitted = await run_startup.waiting('install resource wait')
 
 	// The install claims its place in the core budget (joshuafolkken/kit#3944): a batch opens its lanes
 	// together, and each install ran beside the other lanes' gates off the ledger.
 	const result = await core_budget.with_command_reservation(
 		core_budget.CORE_WEIGHTS.install,
-		async () =>
-			await buffered_process.run_buffered_process(INSTALL_ARGUMENTS, {
-				cwd: directory,
-				timeout_ms: INSTALL_TIMEOUT_MS,
-			}),
+		async () => {
+			await admitted()
+
+			return await run_startup.phase(
+				'dependency install',
+				async () =>
+					await buffered_process.run_buffered_process(INSTALL_ARGUMENTS, {
+						cwd: directory,
+						timeout_ms: INSTALL_TIMEOUT_MS,
+					}),
+				{ edge_of: (value) => (buffered_process.is_process_failed(value) ? 'failed' : 'done') },
+			)
+		},
 		{ memory_mb: core_budget.MEMORY_MB.install, command: 'lane install' },
 	)
 

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

@@ -5,7 +5,9 @@ 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 { run_event_setup } from '#scripts/run/event/run-event-setup'
+import { run_startup } from '#scripts/run/startup/run-startup'
 import { execa } from 'execa'
+import { lane_dispatch_dependency } from './lane-dispatch-dependency'
 import { lane_launch_admission } from './lane-launch-admission'
 import { lane_launch_pending } from './lane-launch-pending'
 
@@ -114,7 +116,9 @@ async function prepare(context: LaunchContext, directory: string): Promise<JoshR
 
 	await run_event_setup.emit(run_event_setup.installing(issue))
 
-	return await install(directory)
+	return await run_startup.phase('dependency reinstall', async () => await install(directory), {
+		edge_of: (value) => (value.code === SUCCESS_EXIT_CODE ? 'done' : 'failed'),
+	})
 }
 
 async function close_if_vacant(lane: LaneInfo | undefined): Promise<void> {
@@ -144,30 +148,47 @@ async function lane_directory(issue: string): Promise<JoshResult> {
 	return await josh_command.josh_run(['lane:open', issue], should_forward_stderr)
 }
 
-// The launch chain in-process. The CLI prints the pid; `backlog:drive` launches through this same
-// chain. The dispatch is said on the run's stream before it starts, so the board draws a lane that is
-// ready apart from one still being filled.
-async function launch_admitted(context: LaunchContext): Promise<LaunchOutcome> {
-	const opened = await lane_directory(context.issue)
-
-	if (opened.code !== SUCCESS_EXIT_CODE) return refused('unopened', opened)
-
-	const prepared = await prepare(context, opened.out)
+function dispatch_edge(value: JoshResult): 'done' | 'failed' | 'waiting' {
+	if (value.code === lane_dispatch_dependency.WAIT_EXIT_CODE) return 'waiting'
 
-	if (prepared.code !== SUCCESS_EXIT_CODE) return refused('failed', prepared)
+	return value.code === SUCCESS_EXIT_CODE ? 'done' : 'failed'
+}
 
+async function dispatch(context: LaunchContext): Promise<LaunchOutcome> {
 	await run_event_setup.emit(run_event_setup.dispatching(context.issue))
 
-	const dispatched = await josh_command.josh_run(
-		['lane:dispatch', context.issue],
-		should_forward_stderr,
+	const dispatched = await run_startup.phase(
+		'worker dispatch',
+		async () =>
+			await josh_command.josh_run(['lane:dispatch', context.issue], should_forward_stderr),
+		{ edge_of: dispatch_edge },
 	)
 
+	if (dispatched.code === lane_dispatch_dependency.WAIT_EXIT_CODE) {
+		await close_if_vacant(await lane_registry.find_open_lane(context.issue))
+
+		return { kind: 'waiting' }
+	}
+
 	if (dispatched.code !== SUCCESS_EXIT_CODE) return refused('failed', dispatched)
 
 	return { kind: 'launched', pid: dispatched.out }
 }
 
+// The CLI and driver share this chain, including retryable dependency refusals.
+async function launch_admitted(context: LaunchContext): Promise<LaunchOutcome> {
+	const opened = await run_startup.phase(
+		'lane creation',
+		async () => await lane_directory(context.issue),
+		{ edge_of: (value) => (value.code === SUCCESS_EXIT_CODE ? 'done' : 'failed') },
+	)
+	if (opened.code !== SUCCESS_EXIT_CODE) return refused('unopened', opened)
+	const prepared = await prepare(context, opened.out)
+	if (prepared.code !== SUCCESS_EXIT_CODE) return refused('failed', prepared)
+
+	return await dispatch(context)
+}
+
 async function launch_lane(context: LaunchContext): Promise<LaunchOutcome> {
 	return await lane_launch_admission.launch(context, launch_admitted)
 }

package/scripts/lane/lane-ledger-kind.ts

@@ -2,6 +2,7 @@
 // apart so a schema module of its own can name its kind without importing the union it joins.
 
 const KIND = {
+	STARTUP: 'startup',
 	MERGE: 'merge',
 	GATE: 'gate',
 	LOAD: 'load',
@@ -17,6 +18,7 @@ const KIND = {
 	OFFERABLE: 'offerable',
 	OFFER: 'offer',
 	CORE_WAIT: 'core-wait',
+	CORE_ADMISSION: 'core-admission',
 	UNIT_FILES: 'unit-files',
 	TEST_RELATED: 'test-related',
 	TEST_PINNED: 'test-pinned',

package/scripts/lane/lane-ledger-schema-ship.ts

@@ -6,13 +6,17 @@ import { lane_ledger_kind } from './lane-ledger-kind'
 
 const { KIND } = lane_ledger_kind
 
-// Every early-push decision, including a skip before a push process could start.
+// Every early-push decision, including a skip before a push process could start. `head` is the commit
+// it decided on and `slots` how many review slots the round opened (joshuafolkken/kit#7503), absent
+// where unknown and on a line recorded before it had them.
 const early_push_schema = z.object({
 	kind: z.literal(KIND.EARLY_PUSH),
 	at: z.string(),
 	issue: z.number().optional(),
 	source: z.enum(['review', 'ship']),
 	result: z.string(),
+	head: z.string().optional(),
+	slots: z.number().optional(),
 })
 
 // A `josh ship` that stopped on `issue`: `reason` is the stage it stopped at, or `conflict` — the

package/scripts/lane/lane-ledger-schema.ts

@@ -1,3 +1,4 @@
+import { run_startup_schema } from '#scripts/run/startup/run-startup-schema'
 import { z } from 'zod'
 import { lane_ledger_kind } from './lane-ledger-kind'
 import { lane_ledger_pinned_origin } from './lane-ledger-pinned-origin'
@@ -138,11 +139,23 @@ const offerable_schema = z.object({
 // command itself, so a wait inside a gate, a scoped check or a ship lands in one record. `issue` is the
 // lane the claim ran in, absent outside a lane (joshuafolkken/kit#4382).
 const core_wait_schema = z.object({
-	kind: z.literal(KIND.CORE_WAIT),
+	kind: z.enum([KIND.CORE_WAIT, KIND.CORE_ADMISSION]),
 	at: z.string(),
 	command: z.string(),
 	waited_ms: z.number(),
 	issue: z.number().optional(),
+	admission_reason: z.string().optional(),
+	overflow: z.boolean().optional(),
+	budget_cores: z.number().optional(),
+	budget_memory_mb: z.number().optional(),
+	available_mb: z.number().optional(),
+	busy_cores: z.number().optional(),
+	requested_cores: z.number().optional(),
+	granted_cores: z.number().optional(),
+	memory_mb: z.number().optional(),
+	wait_reason: z.string().optional(),
+	admission_waited_ms: z.number().optional(),
+	memory_pressured: z.boolean().optional(),
 })
 // One vitest run's slowest test files, each with its wall time from environment setup to its last
 // test, so a unit run whose wall time far outran its CPU names the file it stalled on
@@ -247,6 +260,7 @@ const push_miss_schema = z.object({
 const limit_schema = z.object({ kind: z.literal(KIND.LIMIT), at: z.string(), limit: z.number() })
 const entry_schema = z.discriminatedUnion('kind', [
 	early_push_schema,
+	run_startup_schema.entry_schema,
 	merge_schema,
 	gate_schema,
 	load_schema,

package/scripts/lane/lane-ledger-write.ts

@@ -192,7 +192,10 @@ async function record_round_two(round_two: RoundTwoRecord, path?: string): Promi
 }
 
 async function record_core_wait(wait: CoreWaitRecord, path?: string): Promise<void> {
-	await record({ kind: KIND.CORE_WAIT, at: now_iso(), ...wait }, path)
+	const is_immediate = wait.admission_reason !== undefined && wait.wait_reason === undefined
+	const kind = is_immediate ? KIND.CORE_ADMISSION : KIND.CORE_WAIT
+
+	await record({ kind, at: now_iso(), ...wait }, path)
 }
 
 async function record_unit_files(

package/scripts/lane/lane-relaunch.ts

@@ -5,6 +5,7 @@ import { detached_launch, type LaunchResult } from '#scripts/run/detached-launch
 import { run_ship_detach } from '#scripts/run/ship/run-ship-detach'
 import { lane_child_invocation } from './lane-child-invocation'
 import { lane_child_marker } from './lane-child-marker'
+import { lane_dispatch_dependency } from './lane-dispatch-dependency'
 import { lane_dispatch_log } from './lane-dispatch-log'
 import type { LaneInfo } from './lane-registry'
 import { lane_seat_start } from './lane-seat-start'
@@ -25,7 +26,11 @@ const OPENAI_PROVIDER = 'openai'
 type RelaunchResult = LaunchResult | { kind: 'rejected'; note: string }
 type Prepared = Exclude<Awaited<ReturnType<typeof agent_argv.resume_argv>>, { kind: 'rejected' }>
 
-function launch(lane: LaneInfo, built: Prepared, on_note: (note: string) => void): RelaunchResult {
+function launch_ready(
+	lane: LaneInfo,
+	built: Prepared,
+	on_note: (note: string) => void,
+): RelaunchResult {
 	return detached_launch.launch(
 		{
 			argv: built.argv,
@@ -48,6 +53,24 @@ function launch(lane: LaneInfo, built: Prepared, on_note: (note: string) => void
 	)
 }
 
+async function launch(
+	lane: LaneInfo,
+	built: Prepared,
+	on_note: (note: string) => void,
+): Promise<RelaunchResult> {
+	const wait = await lane_dispatch_dependency.check(lane.issue)
+
+	if (wait !== undefined) {
+		await lane_dispatch_dependency.defer(lane.issue)
+
+		return { kind: 'rejected', note: wait.reason }
+	}
+
+	await lane_dispatch_dependency.begin(lane.issue)
+
+	return launch_ready(lane, built, on_note)
+}
+
 async function relaunch(
 	lane: LaneInfo,
 	invocation: string,
@@ -62,7 +85,7 @@ async function relaunch(
 		})
 		if (built.kind === 'rejected') return built
 
-		return await lane_seat_start.start(lane, async (seated) => launch(seated, built, on_note))
+		return await lane_seat_start.start(lane, async (seated) => await launch(seated, built, on_note))
 	} catch (error) {
 		return { kind: 'failed', note: error_text.message_of(error) }
 	}

package/scripts/lane/lane-state-record.ts

@@ -9,6 +9,7 @@ import { z } from 'zod'
 // lanes out of the worker share (`unit-run-marker.ts`, joshuafolkken/kit#6916).
 
 const STATE_SUFFIX = '.json'
+const DEPENDENCY_WAIT_COMMAND = 'lane:dependency-wait'
 // `as const` so the literal type survives export on `lane_state_record` (a bare const widens there).
 const HUMAN_REVIEW = 'human-review' as const
 const LANE_STATES = ['open', 'running', 'paused', HUMAN_REVIEW, 'ended'] as const
@@ -62,6 +63,7 @@ function is_idle(state_root: string, common: string, issue: string): boolean {
 }
 
 const lane_state_record = {
+	DEPENDENCY_WAIT_COMMAND,
 	HUMAN_REVIEW,
 	LANE_STATES,
 	STATE_SUFFIX,