@joshuafolkken/kit 1.3000.0 → 1.3041.0

package/scripts/lane/lane-stage-events.ts

@@ -0,0 +1,103 @@
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-stream'
+import { run_ship_stage } from '#scripts/run/ship/run-ship-stage'
+import { lane_ledger, type LedgerEntry, type StageEntry } from './lane-ledger'
+import { lane_stop_stats } from './lane-stop-stats'
+
+// The bounded board stream is not a historical stage store. Completed ledger intervals survive
+// compaction and archive rotation; merge them with surviving events before attributing lane time.
+const { EVENT_KIND } = run_event_stream
+const { PHASE, STAGE } = run_ship_stage
+const SHIP_STAGES: ReadonlySet<string> = new Set([
+	...Object.values(STAGE),
+	lane_ledger.PRE_DETACH_STAGE,
+])
+
+function is_ship(entry: LedgerEntry, issue: number): entry is StageEntry {
+	return (
+		entry.kind === lane_ledger.KIND.STAGE && entry.issue === issue && SHIP_STAGES.has(entry.stage)
+	)
+}
+
+function event_at(at_ms: number, issue: number, words: string): RunEvent {
+	return {
+		pos: 0,
+		at: new Date(at_ms).toISOString(),
+		kind: EVENT_KIND.SHIP_STAGE,
+		text: `${issue_cite.plain_for('program', issue)} ${words}`,
+	}
+}
+
+function interval_events(entry: StageEntry, issue: number): Array<RunEvent> {
+	const end_ms = Date.parse(entry.at)
+	if (!Number.isFinite(end_ms) || entry.elapsed_ms <= 0) return []
+
+	return [
+		event_at(end_ms - entry.elapsed_ms, issue, `${entry.stage} ${PHASE.START}`),
+		event_at(end_ms, issue, `${entry.stage} ${PHASE.DONE}`),
+	]
+}
+
+function is_lane_ship(event: RunEvent, issue: number): boolean {
+	return event.kind === EVENT_KIND.SHIP_STAGE && lane_stop_stats.issue_of(event) === issue
+}
+
+function change(active: Map<string, RunEvent>, event: RunEvent): void {
+	if (event.kind === EVENT_KIND.STOP) {
+		active.clear()
+
+		return
+	}
+
+	const { stage, phase } = run_ship_stage.words_of(event.text)
+	if (phase === PHASE.SKIPPED) return
+	if (phase === PHASE.START) active.set(stage, event)
+	else active.delete(stage)
+}
+
+// Parallel stages occupy one wall-clock interval. The most recently started stage owns an overlap;
+// when it ends, the still-running stage resumes rather than opening a false gap.
+function exclusive(events: ReadonlyArray<RunEvent>, issue: number): Array<RunEvent> {
+	const active = new Map<string, RunEvent>()
+
+	return events.map((event) => {
+		change(active, event)
+		const latest = [...active.values()].at(-1)
+		if (latest === undefined) return event
+		const { stage } = run_ship_stage.words_of(latest.text)
+
+		return event_at(Date.parse(event.at), issue, `${stage} ${PHASE.START}`)
+	})
+}
+
+function stop_events(entries: ReadonlyArray<LedgerEntry>, issue: number): Array<RunEvent> {
+	return entries.flatMap((entry) =>
+		entry.kind === lane_ledger.KIND.STOP && entry.issue === issue
+			? { ...event_at(Date.parse(entry.at), issue, entry.reason), kind: EVENT_KIND.STOP }
+			: [],
+	)
+}
+
+function of(
+	entries: ReadonlyArray<LedgerEntry>,
+	events: ReadonlyArray<RunEvent>,
+	issue: number,
+): ReadonlyArray<RunEvent> {
+	const restored = entries
+		.filter((entry) => is_ship(entry, issue))
+		.flatMap((entry) => interval_events(entry, issue))
+	const ship = [
+		...events.filter((event) => is_lane_ship(event, issue)),
+		...restored,
+		...stop_events(entries, issue),
+	].toSorted((left, right) => Date.parse(left.at) - Date.parse(right.at))
+
+	return [
+		...events.filter((event) => !is_lane_ship(event, issue)),
+		...exclusive(ship, issue),
+	].toSorted((left, right) => Date.parse(left.at) - Date.parse(right.at))
+}
+
+const lane_stage_events = { of }
+
+export { lane_stage_events }

package/scripts/lane/lane-stats-tables.ts

@@ -22,6 +22,7 @@ import { lane_size_stats } from './lane-size-stats'
 import { lane_split_stats } from './lane-split-stats'
 import { lane_stage_stats } from './lane-stage-stats'
 import type { StatsWindow } from './lane-stats'
+import { lane_stop_check_stats } from './lane-stop-check-stats'
 import { lane_stop_stats } from './lane-stop-stats'
 import { lane_test_related_stats } from './lane-test-related-stats'
 import type { ToolCall } from './lane-transcript-calls'
@@ -61,6 +62,8 @@ function stop_tables(
 ): Array<string> {
 	return [
 		lane_stop_stats.table(entries, window, events),
+		lane_stop_check_stats.check_table(entries, window, events),
+		lane_stop_check_stats.longest_table(entries, window, events),
 		lane_chain_stop_stats.table(entries, window),
 		lane_gap_stats.table(entries, window, events),
 		lane_cut_stats.table(entries, window, events),

package/scripts/lane/lane-stop-check-stats.ts

@@ -0,0 +1,117 @@
+import { issue_cite } from '#scripts/issue/issue-cite'
+import type { RunEvent } from '#scripts/run/event/run-event-stream'
+import { run_ship_stage } from '#scripts/run/ship/run-ship-stage'
+import { run_ship_stop_cause } from '#scripts/run/ship/run-ship-stop-cause'
+import type { LedgerEntry } from './lane-ledger'
+import { lane_stage_stats } from './lane-stage-stats'
+import { lane_stats, type StatsWindow } from './lane-stats'
+import { lane_stop_stats, type StopWait } from './lane-stop-stats'
+
+// What the stop table's waits were spent on (joshuafolkken/kit#7333), printed by `josh lane:stats` under
+// it: the period's followup `check` stops by the CI check that failed — so the check worth fixing first
+// is a number — and the period's longest stops, each with its issue and the instant it stopped, so a
+// wait that ran overnight or on a person reads as itself. The waits are the stop table's own
+// (`lane-stop-stats.ts`).
+
+const CHECK_COLUMNS = [
+	'failed check',
+	'stops',
+	'wait total (min)',
+	'wait max (min)',
+	'not resumed',
+] as const
+const LONGEST_COLUMNS = ['longest stop', 'issue', 'stopped at', 'causes', 'wait (min)'] as const
+const LONGEST_ROWS = 10
+// A followup check stop recorded before it named its checks, or whose wait named none.
+const NO_CHECK = 'none named'
+const CAUSE_SEPARATOR = ', '
+const { STAGE } = run_ship_stage
+const { CAUSE } = run_ship_stop_cause
+
+function is_followup_check({ stop }: StopWait): boolean {
+	return stop.reason === STAGE.FOLLOWUP && stop.cause === CAUSE.CHECK
+}
+
+function checks_of({ stop }: StopWait): ReadonlyArray<string> {
+	return stop.checks ?? [NO_CHECK]
+}
+
+interface CheckRow {
+	cells: Array<string>
+	total_ms: number
+}
+
+// One failed check's row; a stop that named two checks counts once under each.
+function check_row(check: string, waits: ReadonlyArray<StopWait>): CheckRow {
+	const of_check = waits.filter((wait) => checks_of(wait).includes(check))
+	const ended = of_check
+		.map((wait) => wait.wait_ms)
+		.filter((value) => lane_stage_stats.is_number(value))
+	const total = lane_stop_stats.total(ended)
+	const cells = [
+		check,
+		String(of_check.length),
+		lane_stage_stats.cell(total),
+		lane_stage_stats.cell(lane_stats.peak(ended)),
+		String(of_check.length - ended.length),
+	]
+
+	return { cells, total_ms: total ?? 0 }
+}
+
+function header(columns: ReadonlyArray<string>): Array<string> {
+	return [lane_stats.to_row(columns), lane_stats.to_row(columns.map(() => '---'))]
+}
+
+// The period's followup check stops by failed check, the longest total wait first.
+function check_table(
+	entries: ReadonlyArray<LedgerEntry>,
+	window: StatsWindow,
+	events: ReadonlyArray<RunEvent> = [],
+): string {
+	const waits = lane_stop_stats
+		.waits_in(entries, window, events)
+		.filter((wait) => is_followup_check(wait))
+	const checks = new Set(waits.flatMap((wait) => checks_of(wait)))
+	const rows = [...checks].map((check) => check_row(check, waits))
+	const ranked = rows.toSorted((left, right) => right.total_ms - left.total_ms)
+
+	return [...header(CHECK_COLUMNS), ...ranked.map(({ cells }) => lane_stats.to_row(cells))].join(
+		'\n',
+	)
+}
+
+// A followup check stop's failed checks, any other stop's causes.
+function causes_cell(wait: StopWait): string {
+	return (is_followup_check(wait) ? checks_of(wait) : wait.causes).join(CAUSE_SEPARATOR)
+}
+
+function longest_row(wait: StopWait): string {
+	return lane_stats.to_row([
+		wait.reason,
+		issue_cite.plain_for('terminal', wait.stop.issue),
+		wait.stop.at,
+		causes_cell(wait),
+		lane_stage_stats.cell(wait.wait_ms),
+	])
+}
+
+// The period's ended stops, the longest wait first, at most `LONGEST_ROWS` of them.
+function longest_table(
+	entries: ReadonlyArray<LedgerEntry>,
+	window: StatsWindow,
+	events: ReadonlyArray<RunEvent> = [],
+): string {
+	const ended = lane_stop_stats
+		.waits_in(entries, window, events)
+		.filter((wait) => lane_stage_stats.is_number(wait.wait_ms))
+	const ranked = ended.toSorted((left, right) => (right.wait_ms ?? 0) - (left.wait_ms ?? 0))
+
+	const rows = ranked.slice(0, LONGEST_ROWS).map((wait) => longest_row(wait))
+
+	return [...header(LONGEST_COLUMNS), ...rows].join('\n')
+}
+
+const lane_stop_check_stats = { LONGEST_ROWS, NO_CHECK, check_table, longest_table }
+
+export { lane_stop_check_stats }

package/scripts/lane/lane-stop-stats.ts

@@ -48,8 +48,10 @@ const NO_CAUSES = '-'
 const NOTICED = ' (noticed)'
 
 // `causes` is a preflight stop's unmet preconditions or a review stop's blocking finding kinds, every
-// one of them, else the stop's one cause.
+// one of them, else the stop's one cause. `stop` is the ledger entry, read for its issue, its instant
+// and a followup stop's failed checks (`lane-stop-check-stats.ts`).
 interface StopWait {
+	stop: StopEntry
 	reason: string
 	causes: ReadonlyArray<string>
 	wait_ms: number | undefined
@@ -143,6 +145,7 @@ function waits_of(
 	notices: ReadonlyArray<IssueAt>,
 ): Array<StopWait> {
 	return entries.filter(is_stop).map((stop) => ({
+		stop,
 		reason: stop.reason,
 		causes: causes_of(stop, notices),
 		wait_ms: wait_ms(instant_of(stop), ends),
@@ -183,15 +186,25 @@ function reason_row(reason: string, waits: ReadonlyArray<StopWait>): string {
 	])
 }
 
-// The period's table: `entries` is the whole ledger, filtered here to `window` — only the stops are; a
-// wait may end after the period's last stop. `events` is the run's event stream, read for its parks.
+// The period's stops with their waits: `entries` is the whole ledger, filtered here to `window` — only
+// the stops are; a wait may end after the period's last stop. `events` is the run's event stream, read
+// for its parks.
+function waits_in(
+	entries: ReadonlyArray<LedgerEntry>,
+	window: StatsWindow,
+	events: ReadonlyArray<RunEvent> = [],
+): Array<StopWait> {
+	const ends = ends_of(entries, parks_of(events))
+
+	return waits_of(lane_stats.in_window(entries, window), ends, notices_of(entries))
+}
+
 function table(
 	entries: ReadonlyArray<LedgerEntry>,
 	window: StatsWindow,
 	events: ReadonlyArray<RunEvent> = [],
 ): string {
-	const ends = ends_of(entries, parks_of(events))
-	const waits = waits_of(lane_stats.in_window(entries, window), ends, notices_of(entries))
+	const waits = waits_in(entries, window, events)
 
 	return [
 		lane_stats.to_row(COLUMNS),
@@ -200,6 +213,17 @@ function table(
 	].join('\n')
 }
 
-const lane_stop_stats = { REASONS, dispatches_of, ends_of, events_of, issue_of, table, wait_ms }
+const lane_stop_stats = {
+	REASONS,
+	dispatches_of,
+	ends_of,
+	events_of,
+	issue_of,
+	table,
+	total,
+	wait_ms,
+	waits_in,
+}
 
+export type { StopWait }
 export { lane_stop_stats }

package/scripts/lane/lane-why-causes.ts

@@ -1,3 +1,4 @@
+import { git_pr_checks_failed } from '#scripts/gh/git-pr-checks-failed'
 import { issue_cite } from '#scripts/issue/issue-cite'
 import { lane_ci_path_stats } from './lane-ci-path-stats'
 import type { LedgerEntry } from './lane-ledger'
@@ -28,28 +29,19 @@ const KNOWN: ReadonlyArray<KnownCause> = [
 	},
 	{ key: 'byte budget', log: /byte budget/iu },
 ]
-// `git-pr-checks-eval.ts`'s `PR checks failed (failed checks: <a>, <b>; …).`, ended by the next
-// reason or the closing `).` so a matrix name such as `Unit Tests (3/6)` stays whole.
-const FAILED_CHECKS = /failed checks: (?<names>.+?)(?=; |\)\.$)/gmu
 const NAME_SEPARATOR = ', '
 
 function key_of(check: string): string {
 	return KNOWN.find((known) => known.check?.test(check) === true)?.key ?? check.toLowerCase()
 }
 
-function failed_checks(log: string): Array<string> {
-	return [...log.matchAll(FAILED_CHECKS)]
-		.flatMap((match) => (match.groups?.['names'] ?? '').split(NAME_SEPARATOR))
-		.map((name) => name.trim())
-		.filter((name) => name !== '')
-}
-
 function log_keys(log: string | undefined): Array<string> {
 	if (log === undefined) return []
 
 	const verdicts = KNOWN.filter((known) => known.log?.test(log) === true)
+	const failed = git_pr_checks_failed.names_of(log)
 
-	return [...failed_checks(log).map((check) => key_of(check)), ...verdicts.map(({ key }) => key)]
+	return [...failed.map((check) => key_of(check)), ...verdicts.map(({ key }) => key)]
 }
 
 // `issue`'s cause keys, each once: from its ship `log` (`undefined` when gone) and its ledger rows.

package/scripts/lane/openai-lane-supervisor-owner.ts

@@ -28,6 +28,7 @@ const state_schema = z.object({
 	owner_nonce: z.string(),
 	child_pid: z.number().int().positive().optional(),
 	child_process_start: z.string().optional(),
+	resume_cut: z.string().optional(),
 	epoch: z.number().int().nonnegative(),
 })
 
@@ -140,15 +141,26 @@ function remove_stale_owner(target: string, previous: SupervisorOwner | undefine
 	return true
 }
 
+function previous_resume(
+	lane_directory: string,
+	owner: SupervisorOwner | undefined,
+): string | undefined {
+	if (owner === undefined) return undefined
+
+	return read_state(lane_directory, owner.nonce)?.resume_cut
+}
+
 function claim(issue: string, lane_directory: string, nonce: string): SupervisorOwner | undefined {
 	const target = marker_path(lane_directory)
 	const previous = read(lane_directory)
 	if (!remove_stale_owner(target, previous)) return undefined
 	const child = carried_child(lane_directory, previous)
+	const resume_cut = previous_resume(lane_directory, previous)
 	const owner = { issue, nonce, ...process_identity.own_fields() }
 	if (!stamp_file.create_stamp(target, owner)) return undefined
 	stamp_file.replace_stamp(state_path(lane_directory), {
 		owner_nonce: nonce,
+		resume_cut,
 		epoch: 0,
 		...(child !== undefined && {
 			child_pid: child.pid,

package/scripts/lane/openai-lane-supervisor.ts

@@ -67,6 +67,7 @@ interface Generation {
 	owner: SupervisorOwner
 	profile: AgentProfile
 	invocation?: string
+	resume_cut?: string | undefined
 }
 
 function completion_code(result: ChildResult, ship: string): number {
@@ -81,6 +82,7 @@ function record_child(generation: Generation, child_pid: number): void {
 		owner_nonce: owner.nonce,
 		epoch,
 		child_pid,
+		resume_cut: generation.resume_cut,
 		...(child_process_start !== undefined && { child_process_start }),
 	})
 }
@@ -97,8 +99,34 @@ function child_result(
 	return { kind: 'abnormal', note }
 }
 
-async function run_child(generation: Generation): Promise<ChildResult> {
+// An unchanged, unspent handoff after its successor exited is a failed resume, not a new cut.
+// Persist the attempt before launching so a recovered supervisor makes the same decision.
+async function prepare_generation(generation: Generation): Promise<Generation | undefined> {
+	const { lane, owner } = generation
+	const cut = await standing_cut(lane.issue)
+	if (cut === undefined) return { ...generation, resume_cut: undefined }
+	const resume_cut = JSON.stringify(cut)
+
+	if (read_state(lane.directory, owner.nonce)?.resume_cut === resume_cut) {
+		console.error(
+			`OpenAI supervisor ${session_cite.issue(lane.issue)}: resume did not adopt cut ${cut.cut_at}; stopping with work and cut preserved`,
+		)
+
+		return undefined
+	}
+
+	return { ...generation, resume_cut }
+}
+
+async function launch_child(generation: Generation): Promise<ChildResult> {
 	const { lane, profile, is_resume } = generation
+
+	update(lane.directory, generation.owner, {
+		owner_nonce: generation.owner.nonce,
+		epoch: generation.epoch,
+		resume_cut: generation.resume_cut,
+	})
+
 	const result = await detached_launch.launch_attached(
 		{
 			argv: child_argv(lane, profile, is_resume, generation.invocation),
@@ -124,6 +152,13 @@ async function stop_invocation(issue: string): Promise<string> {
 	return current?.stop_invocation ?? lane_child_invocation.ship_stop_invocation(issue)
 }
 
+async function run_child(generation: Generation): Promise<ChildResult> {
+	const ready = await prepare_generation(generation)
+	if (ready === undefined) return { kind: LAUNCH_FAILED_KIND, note: 'cut resume failed' }
+
+	return await launch_child(ready)
+}
+
 async function run_generations(generation: Generation): Promise<number> {
 	const prior = await openai_lane_ship.current(generation.lane.issue)
 	const result = await run_child(generation)

package/scripts/lib/home-tilde.ts

@@ -0,0 +1,24 @@
+import os from 'node:os'
+
+// A string drawn on a screen with the home directory written out as `~`: the absolute path carries
+// the OS account name, which is often the user's real name and leaks in a screenshot or a recording
+// (joshuafolkken/kit#7342). A home that is the root, or unknown, names no account and is left as is.
+const TILDE = '~'
+const ROOT = '/'
+// The home only where a path segment ends, so a sibling account such as `/Users/anna` beside
+// `/Users/ann` is not drawn as `~a`.
+const SEGMENT_CONTINUES = /^[\w.-]/u
+
+function mask(text: string): string {
+	const home = os.homedir()
+	if (home === '' || home === ROOT) return text
+
+	const [head = '', ...rest] = text.split(home)
+	const masked = rest.map((part) => `${SEGMENT_CONTINUES.test(part) ? home : TILDE}${part}`)
+
+	return `${head}${masked.join('')}`
+}
+
+const home_tilde = { mask }
+
+export { home_tilde }

package/scripts/lib/package-manifest.ts

@@ -25,6 +25,29 @@ const GATE_STEPS_SCHEMA = z
 		message: 'step names must be unique',
 	})
 const GATE_SCHEMA = z.object({ steps: GATE_STEPS_SCHEMA.optional() })
+// A worker profile a lane may run on: `profiles` runs weakest first, which is the escalation order.
+// The model and effort are checked against the agent rules by `agent-worker-profile.ts`.
+const WORKER_PROFILE_SCHEMA = z.strictObject({
+	name: z.string().min(1),
+	model: z.string().min(1),
+	effort: z.string().min(1),
+	when: z.string().min(1),
+})
+const WORKER_PROFILES_SCHEMA = z
+	.array(WORKER_PROFILE_SCHEMA)
+	.min(1)
+	.refine((profiles) => new Set(profiles.map((profile) => profile.name)).size === profiles.length, {
+		message: 'profile names must be unique',
+	})
+const WORKER_SCHEMA = z
+	.strictObject({
+		default: z.string().min(1),
+		escalate: z.boolean().default(false),
+		profiles: WORKER_PROFILES_SCHEMA,
+	})
+	.refine((worker) => worker.profiles.some((profile) => profile.name === worker.default), {
+		message: 'default must name one of the profiles',
+	})
 const josh_schemas = {
 	format: z.object({ josh: z.object({ format: FORMAT_SCHEMA.optional() }).optional() }),
 	gate_steps: z.object({ josh: z.object({ gate: GATE_SCHEMA.optional() }).optional() }),
@@ -33,6 +56,7 @@ const josh_schemas = {
 		josh: z.object({ progress_interval_minutes: z.number().positive() }).optional(),
 	}),
 	review_gate: z.object({ josh: z.object({ review_gate: REVIEW_GATE_SCHEMA }).optional() }),
+	worker: z.object({ josh: z.object({ worker: WORKER_SCHEMA.optional() }).optional() }),
 }
 
 function manifest_path(directory: string): string {
@@ -81,6 +105,8 @@ const package_manifest = {
 
 type GateStepDefinition = z.infer<typeof GATE_STEP_SCHEMA>
 type FormatScope = z.infer<typeof FORMAT_SCHEMA>
+type WorkerConfig = z.infer<typeof WORKER_SCHEMA>
+type WorkerProfileDefinition = z.infer<typeof WORKER_PROFILE_SCHEMA>
 
-export type { FormatScope, GateStepDefinition }
+export type { FormatScope, GateStepDefinition, WorkerConfig, WorkerProfileDefinition }
 export { PACKAGE_JSON, REVIEW_GATE_SCHEMA, package_manifest }