@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/lane/lane-net-time.ts

@@ -0,0 +1,212 @@
+import { MS_PER_MINUTE } from '#scripts/lib/timeouts'
+import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-stream'
+import type { LedgerEntry } from './lane-ledger'
+import { lane_sleep } from './lane-sleep'
+import { lane_spans, type IssueAt, type Span } from './lane-spans'
+import { lane_stage_stats } from './lane-stage-stats'
+import { lane_stop_stats } from './lane-stop-stats'
+import { lane_yield } from './lane-yield'
+
+// A lane's net time (joshuafolkken/kit#4749): from its issue's first dispatch to its merge, less the
+// waits no fix in the lane shortens — a park (the issue waits on a person's decision), an outage and a
+// usage-limit stop (joshuafolkken/kit#4745), each until the issue's next ship stage, re-dispatch or
+// another of the two, the wait `josh lane:stats` derives for a stop (`lane-stop-stats.ts`) — and the
+// host's sleeps (joshuafolkken/kit#5032), whatever the issue (`lane-sleep.ts`), and a yield's wait for
+// the issue's next dispatch (joshuafolkken/kit#5216), no lane seat held while the holder runs. A ship
+// stop is not taken out: a relaunched child works through its wait. `josh lane:net` prints it, and a
+// causing-lane line declares it (`issue-priority.ts`).
+
+const { EVENT_KIND } = run_event_stream
+
+interface LaneSpan {
+	from_ms: number
+	to_ms: number
+}
+
+function entries_of(entries: ReadonlyArray<LedgerEntry>, issue: number): Array<LedgerEntry> {
+	return entries.filter((entry) => 'issue' in entry && entry.issue === issue)
+}
+
+// The first dispatch of `issue` to its merge, or `undefined` while either is missing or the merge comes
+// first.
+function span_of(entries: ReadonlyArray<LedgerEntry>, issue: number): LaneSpan | undefined {
+	const of_issue = entries_of(entries, issue)
+	const from = of_issue.find((entry) => lane_stage_stats.is_dispatch(entry))
+	const to = of_issue.findLast((entry) => lane_stage_stats.is_merge(entry))
+
+	if (from === undefined || to === undefined) return undefined
+
+	const span = { from_ms: Date.parse(from.at), to_ms: Date.parse(to.at) }
+
+	return span.to_ms < span.from_ms ? undefined : span
+}
+
+function holds_of(events: ReadonlyArray<RunEvent>): Array<IssueAt> {
+	return [
+		...lane_stop_stats.events_of(events, EVENT_KIND.PARK),
+		...lane_stop_stats.events_of(events, EVENT_KIND.OUTAGE),
+		...lane_stop_stats.events_of(events, EVENT_KIND.USAGE_LIMIT),
+	]
+}
+
+// One hold's wait, cut at the merge: a hold nothing ended before it waited until the merge.
+function held_ms(hold: IssueAt, ends: ReadonlyArray<IssueAt>, to_ms: number): number {
+	const left_ms = to_ms - hold.at_ms
+
+	return Math.min(lane_stop_stats.wait_ms(hold, ends) ?? left_ms, left_ms)
+}
+
+function hold_waits(
+	entries: ReadonlyArray<LedgerEntry>,
+	events: ReadonlyArray<RunEvent>,
+	issue: number,
+	span: LaneSpan,
+): Array<LaneSpan> {
+	const holds = holds_of(events)
+	const inside = holds.filter(
+		(hold) => hold.issue === issue && hold.at_ms >= span.from_ms && hold.at_ms < span.to_ms,
+	)
+
+	return inside.map((hold) => {
+		const ends = lane_stop_stats.ends_of(
+			entries,
+			holds.filter((other) => other.at_ms > hold.at_ms),
+		)
+
+		return { from_ms: hold.at_ms, to_ms: hold.at_ms + held_ms(hold, ends, span.to_ms) }
+	})
+}
+
+// `spans` oldest first with every overlap joined, so a park the host slept through is taken out once.
+function joined(spans: ReadonlyArray<LaneSpan>): Array<LaneSpan> {
+	const sorted = spans.toSorted((left, right) => left.from_ms - right.from_ms)
+
+	const kept: Array<LaneSpan> = []
+
+	for (const next of sorted) {
+		const last = kept.at(-1)
+
+		if (last === undefined || next.from_ms > last.to_ms) kept.push({ ...next })
+		else last.to_ms = Math.max(last.to_ms, next.to_ms)
+	}
+
+	return kept
+}
+
+// The host's sleeps (joshuafolkken/kit#5032) cut to `span` and joined: a sleep stops every lane,
+// whatever its issue.
+function slept(events: ReadonlyArray<RunEvent>, span: LaneSpan): Array<LaneSpan> {
+	const cut = lane_sleep.spans(events).map((sleep) => ({
+		from_ms: Math.max(sleep.from_ms, span.from_ms),
+		to_ms: Math.min(sleep.to_ms, span.to_ms),
+	}))
+
+	return joined(cut.filter((sleep) => sleep.to_ms > sleep.from_ms))
+}
+
+// Each yield (`lane:plan` gave the seat back) until its issue's next dispatch, every issue's — the
+// `yield → redispatch` gap `josh lane:stats` prints (`lane-gap-stats.ts`).
+function yield_spans(
+	entries: ReadonlyArray<LedgerEntry>,
+	events: ReadonlyArray<RunEvent>,
+): Array<Span> {
+	const yields = lane_stop_stats.events_of(
+		events.filter((event) => lane_yield.is_yield(event)),
+		EVENT_KIND.WITHDRAW,
+	)
+
+	return lane_spans.issue_spans({
+		starts: yields,
+		bounds: yields,
+		ends: lane_stop_stats.dispatches_of(entries),
+	})
+}
+
+// `issue`'s yields inside `span`, each until its redispatch, cut at the merge.
+function yielded(
+	entries: ReadonlyArray<LedgerEntry>,
+	events: ReadonlyArray<RunEvent>,
+	issue: number,
+	span: LaneSpan,
+): Array<LaneSpan> {
+	const of_issue = events.filter((event) => lane_stop_stats.issue_of(event) === issue)
+	const inside = yield_spans(entries, of_issue).filter(
+		(wait) => wait.from_ms >= span.from_ms && wait.from_ms < span.to_ms,
+	)
+
+	return inside.map((wait) => ({
+		from_ms: wait.from_ms,
+		to_ms: Math.min(wait.end_ms ?? span.to_ms, span.to_ms),
+	}))
+}
+
+// The waits `net_ms` takes out of `span` — each hold from itself to its end, cut at the merge, each
+// yield until its redispatch, and each sleep of the host — the intervals `josh lane:breakdown` counts
+// as excluded (`lane-breakdown.ts`).
+function waits(
+	entries: ReadonlyArray<LedgerEntry>,
+	events: ReadonlyArray<RunEvent>,
+	issue: number,
+	span: LaneSpan,
+): Array<LaneSpan> {
+	return joined([
+		...hold_waits(entries, events, issue, span),
+		...yielded(entries, events, issue, span),
+		...slept(events, span),
+	])
+}
+
+/**
+ * The net milliseconds of `issue`'s lane, or `undefined` when the ledger holds no dispatch and merge of
+ * it. `events` is the run's event stream, read for the parks and outages.
+ */
+function net_ms(
+	entries: ReadonlyArray<LedgerEntry>,
+	events: ReadonlyArray<RunEvent>,
+	issue: number,
+): number | undefined {
+	const span = span_of(entries, issue)
+
+	if (span === undefined) return undefined
+
+	return waits(entries, events, issue, span).reduce(
+		(left, wait) => left - (wait.to_ms - wait.from_ms),
+		span.to_ms - span.from_ms,
+	)
+}
+
+// The net time in whole minutes, rounded up — the number a causing-lane line declares.
+function net_minutes(
+	entries: ReadonlyArray<LedgerEntry>,
+	events: ReadonlyArray<RunEvent>,
+	issue: number,
+): number | undefined {
+	const net = net_ms(entries, events, issue)
+
+	return net === undefined ? undefined : Math.ceil(net / MS_PER_MINUTE)
+}
+
+// Why `net_ms` has no answer for `issue` (joshuafolkken/kit#4818): the ledger lacks its dispatch or its
+// merge, or holds both with the merge first.
+function missing_reason(entries: ReadonlyArray<LedgerEntry>, issue: number): string {
+	const of_issue = entries_of(entries, issue)
+
+	if (of_issue.every((entry) => !lane_stage_stats.is_dispatch(entry))) return 'no dispatch'
+	if (of_issue.every((entry) => !lane_stage_stats.is_merge(entry))) return 'no merge'
+
+	return 'cause unknown'
+}
+
+const lane_net_time = {
+	missing_reason,
+	net_minutes,
+	net_ms,
+	slept,
+	span_of,
+	waits,
+	yield_spans,
+	yielded,
+}
+
+export { lane_net_time }
+export type { LaneSpan }

package/scripts/lane/lane-open.ts

@@ -1,9 +1,10 @@
-import { mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
+import { mkdirSync, readdirSync, rmSync } from 'node:fs'
 import path from 'node:path'
 import { ENV_FILE_NAME } from '#ports'
 import { git_worktree } from '#scripts/git/git-worktree'
 import { session_cite } from '#scripts/issue/session-cite'
 import { file_reader } from '#scripts/lib/read-file'
+import { eslint_warm } from '#scripts/lint/eslint-warm'
 import { run_event_setup } from '#scripts/run/event/run-event-setup'
 import { lane_cache } from './lane-cache'
 import { lane_environment } from './lane-environment'
@@ -13,6 +14,7 @@ import { lane_paths } from './lane-paths'
 import { lane_registry, type LaneInfo } from './lane-registry'
 import { lane_seed_policy } from './lane-seed'
 import { lane_start_point } from './lane-start-point'
+import { lane_state } from './lane-state'
 
 // Opening a lane: one linked work tree, one branch, one port seed, and the dependencies to run in it.
 //
@@ -175,9 +177,12 @@ function guard_install(lane: LaneInfo, result: InstallResult): void {
 
 // **The install is said on the run's stream as it starts**: it is the long part of opening a lane, and
 // `run:board` draws it apart from the work tree being made. Best-effort, as every stage is.
+// **The eslint daemon is warmed once the install lands, unawaited**, so the child's first edit hook
+// lints warm rather than paying the daemon's start (joshuafolkken/kit#4720).
 async function fill(lane: LaneInfo): Promise<void> {
 	await run_event_setup.emit(run_event_setup.installing(lane.issue))
 	guard_install(lane, await lane_install.install_dependencies(lane.directory))
+	eslint_warm.start(lane.directory)
 }
 
 function build_plan(
@@ -201,6 +206,15 @@ function build_plan(
 	}
 }
 
+async function add_worktree(lane: LaneInfo): Promise<void> {
+	mkdirSync(path.dirname(lane.directory), { recursive: true })
+
+	const start_point = await lane_start_point.resolve_for_branch(lane.branch)
+
+	await git_worktree.worktree_add(lane.directory, lane.branch, start_point)
+	await git_worktree.set_upstream(lane.branch)
+}
+
 // The `.env` is written straight after the work tree exists, because the seed is the reason the
 // lane is being opened. Nothing else is recorded anywhere: that file *is* the record.
 //
@@ -230,12 +244,8 @@ async function materialize(plan: LanePlan, source_root: string): Promise<void> {
 	// genuinely broken lane. The `finally` covers a failure before the `.env`
 	// is written, where nothing was created that should hold it.
 	try {
-		mkdirSync(path.dirname(plan.lane.directory), { recursive: true })
-
-		const start_point = await lane_start_point.resolve_for_branch(plan.lane.branch)
-
-		await git_worktree.worktree_add(plan.lane.directory, plan.lane.branch, start_point)
-		writeFileSync(path.join(plan.lane.directory, ENV_FILE_NAME), plan.environment_content)
+		await add_worktree(plan.lane)
+		lane_registry.write_environment(plan.lane.directory, plan.environment_content)
 		release_seat_lock(plan.seat_lock)
 		lane_cache.seed_caches(source_root, plan.lane.directory)
 		lane_cache.seed_hook_bundles(source_root, plan.lane.directory)
@@ -256,6 +266,13 @@ async function clear_the_way(
 	await lane_leftover.reclaim(lane_paths.lane_directory(root, issue))
 }
 
+// The lane's state record starts here, so no lane opened from now on is without one.
+async function opened(lane: LaneInfo): Promise<OpenOutcome> {
+	await lane_state.record_change({ issue: lane.issue, state: 'open', command: 'lane:open' })
+
+	return { kind: 'opened', lane }
+}
+
 /**
  * Open the lane for `issue`, or say why it was not opened.
  *
@@ -283,7 +300,7 @@ async function open_lane(issue: string): Promise<OpenOutcome> {
 
 	await materialize(plan, repository_root)
 
-	return { kind: 'opened', lane: plan.lane }
+	return await opened(plan.lane)
 }
 
 const lane_open = {

package/scripts/lane/lane-output.ts

@@ -1,5 +1,3 @@
-import { writeFileSync } from 'node:fs'
-import path from 'node:path'
 import { ENV_FILE_NAME } from '#ports'
 import type { AgentProfile } from '#scripts/agent/agent-role-profile'
 import { session_cite } from '#scripts/issue/session-cite'
@@ -75,8 +73,8 @@ async function record_output(
 
 	if (content === undefined) return { kind: 'unreadable', lane }
 
-	writeFileSync(
-		path.join(lane.directory, ENV_FILE_NAME),
+	lane_registry.write_environment(
+		lane.directory,
 		lane_environment.with_lane_output(content, output, profile),
 	)
 

package/scripts/lane/lane-overrun-prompt.ts

@@ -0,0 +1,147 @@
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { issue_priority } from '#scripts/issue/issue-priority'
+import { run_event_overrun } from '#scripts/run/event/run-event-overrun'
+
+// What an overrun investigation's session does with the causes it found (joshuafolkken/kit#4751) —
+// pick, group, fold or file each, and record the result — the part of its prompt that reads no record.
+// `lane-overrun.ts` puts what the session reads ahead of it.
+
+// The most causes one investigation files, and the fewest minutes one must cut to be filed
+// (joshuafolkken/kit#4928).
+const MAX_FILINGS = 5
+const MIN_MINUTES = 1
+const PRIORITY_COMMAND = 'pnpm josh issue:priority <N>'
+
+// What a duplicate refusal leads to. A recurrence appends its own cause-loss line to the open issue's
+// body, because the backlog ranking reads them only there and sums them (joshuafolkken/kit#4859,
+// joshuafolkken/kit#4928); the sum can then reach the high floor, which a body edit does not label
+// (joshuafolkken/kit#4960).
+function duplicate_lines(loss_lines: string): ReadonlyArray<string> {
+	return [
+		'On a duplicate refusal, read each candidate with `pnpm josh issue:read <N>`: one that only fixes',
+		'another mechanism, or is only cited, is distinct — reissue with `--distinct <N,…>`; an open one that',
+		'fixes the same mechanism is not filed again but gets a comment recording the recurrence with those four',
+		`and ${loss_lines}, and gets those lines added under its background heading too, the cause-loss line`,
+		`appended beside the ones already there, since ranking sums every \`${issue_priority.CAUSE_PREFIX}\` line`,
+		'and reads only the body (`gh api -X PATCH repos/{owner}/{repo}/issues/<N> -F body=@<file>`). Then',
+		`run \`${PRIORITY_COMMAND}\`, which labels it once the sum reaches the high floor. One`,
+		'closed before this lane yet recurring here is filed anew as a recurrence, its number in `--distinct`.',
+		'A cap refusal is final: stop filing.',
+	]
+}
+
+// The filing command: an overrun's filings name the lane they were found during; the baseline's name none.
+function file_command(origin: number | undefined): string {
+	if (origin === undefined) return 'pnpm josh issue:file'
+
+	return `pnpm josh issue:file --found-during ${String(origin)}`
+}
+
+// Each lane pays a fixed review-to-merge cost, so causes one fix place shares are one issue. A fold
+// skips `issue:file`, so it carries the ranked lines; the lane's minutes give it no label, and the
+// fold applies the cause-loss floor with `issue:priority` (`issue-fold-existing.md`).
+function grouping(origin: number | undefined, loss_lines: string): string {
+	return [
+		'Causes whose fixes touch the same file or mechanism are one issue, an acceptance criterion per',
+		'cause; causes fixed in different places are separate issues. Before filing one, look for an open',
+		'issue that touches the same files (`pnpm josh issue:scout "<title>" --body-file <draft.md>`, each',
+		'candidate read with `pnpm josh issue:read <N>`): when one does, fold its causes into it by',
+		'`.claude/skills/workflow-commands/issue-fold-existing.md` instead of filing, the appended part',
+		`carrying ${loss_lines}; on a verdict other than \`fold\`, file as below.`,
+		'File each other issue with',
+		`\`${file_command(origin)}\`, its body carrying those four per cause, and`,
+		`${loss_lines} under its background heading, the cause-loss minutes being what that issue's own`,
+		"causes would cut — backlog ranking orders one priority by them, else by the lane's minutes, which every",
+		'cause of the lane shares, so a filing without either falls behind every declared one.',
+	].join(' ')
+}
+
+// A share over every merge thins a new mechanism's cost below any line (joshuafolkken/kit#4928), so the
+// causes are picked by the minutes a fix would cut from what was read, largest first. `scope` names
+// that span: one lane, or the baseline's merge.
+function selection_lines(scope: string): ReadonlyArray<string> {
+	const limit = `${String(MAX_FILINGS)} causes`
+
+	return [
+		`Estimate each cause's reducible minutes: what its fix would cut from ${scope}. Time the work`,
+		'inherently takes (a CI wait the pipeline requires, a review) counts only for the part a fix removes,',
+		'and not at all when no fix removes any.',
+		`Take at most the ${limit} with the most reducible minutes, largest first, each cutting`,
+		`${String(MIN_MINUTES)} minute or more, and drop the rest: file or fold only those.`,
+		'File a defect — a tool did something unneeded or wrong (a rerun on an unchanged tree, a lost scope)',
+		'— as `- 種別: 不具合`, any other cause as `- 目的: 時間短縮`.',
+	]
+}
+
+// A reach count measured by a hand-written probe, and a before / after criterion beside the fix, cost
+// #5202's lane its implement time (joshuafolkken/kit#5238).
+const MEASUREMENT_LINES = [
+	'Measure a reach test count — the test files `pnpm josh test:related` runs for a changed file — with',
+	'`pnpm josh test:reach <file…>`.',
+	'Put a measurement criterion (a before / after recorded as an Issue comment) in a prior `--route split`',
+	'issue, never in the issue that carries the fix.',
+]
+
+// The result's vocabulary, recorded as the note `template` names with `<result>` in it.
+function result_lines(template: string): ReadonlyArray<string> {
+	return [
+		`Then record the result: \`pnpm josh run:event --append note "${template}"\`,`,
+		`the result being \`${run_event_overrun.folded_result(['<A>', '<B>'])}\` naming every issue you folded into`,
+		`when you folded any, else \`${run_event_overrun.FILED_RESULT}\` when you filed any, \`${run_event_overrun.recurred_result('<N>')}\``,
+		`when you only commented a recurrence on #<N>, else \`${run_event_overrun.none_result('<why, in about 15 characters>')}\`.`,
+	]
+}
+
+// How an investigation's causes are handled: the lane its filings were found during, if any, the ranked
+// lines each filing carries, the note its result is recorded as, and the span a cause's reducible
+// minutes are cut from.
+interface CauseHandling {
+	origin: number | undefined
+	loss_lines: string
+	template: string
+	scope: string
+}
+
+// The filing rules an investigation's causes follow, shared by the overrun and the baseline
+// investigation (joshuafolkken/kit#4887).
+function cause_handling(rules: CauseHandling): string {
+	return [
+		...selection_lines(rules.scope),
+		grouping(rules.origin, rules.loss_lines),
+		...MEASUREMENT_LINES,
+		...duplicate_lines(rules.loss_lines),
+		...result_lines(rules.template),
+	].join(' ')
+}
+
+// The lines backlog ranking reads (joshuafolkken/kit#4861): the cause's own minutes, else the lane's
+// `minutes`, cited to lane `issue`.
+function loss_lines_of(issue: number, minutes: string): string {
+	const cite = issue_cite.plain(issue)
+
+	return `\`- 原因のレーン: ${minutes} 分（${cite}）\` and \`${issue_priority.CAUSE_PREFIX} <分> 分\``
+}
+
+// The breakdown the overrun's prompt leads with orders the search (joshuafolkken/kit#4995); a stage no
+// fix shortens is named in the result, so the time no filing covers is still accounted for. Only the
+// overrun has a breakdown: the baseline shares `cause_handling`, not this.
+const STAGE_ORDER = [
+	'Search for causes stage by stage, in the order of the net time by stage above, longest first.',
+	`For each stage you judge not reducible, end the result with \`${run_event_overrun.NOT_REDUCIBLE_LEAD}<stage> (<why>)\`.`,
+].join(' ')
+
+// The handling of lane `issue`'s causes, its `minutes` of net time on each filing's ranked lines.
+function handling(issue: number, minutes: number): string {
+	const rules = cause_handling({
+		origin: issue,
+		loss_lines: loss_lines_of(issue, String(minutes)),
+		template: run_event_overrun.ended_text(issue, '<result>'),
+		scope: 'this lane alone, judged from its own record',
+	})
+
+	return `${STAGE_ORDER} ${rules}`
+}
+
+const lane_overrun_prompt = { cause_handling, handling, loss_lines_of }
+
+export { lane_overrun_prompt }