@joshuafolkken/kit 1.1784.0 → 1.2114.0

package/scripts/lane/lane-adopt.ts

@@ -0,0 +1,208 @@
+import { git_gh_issue_read } from '#scripts/gh/git-gh-issue-read'
+import {
+	git_gh_pr_read,
+	read_pull_or_listed,
+	read_pull as read_rest_pull,
+} from '#scripts/gh/git-gh-pr-read'
+import { git_gh_pr_rest } from '#scripts/gh/git-gh-pr-rest'
+import { git_command } from '#scripts/git/git-command'
+import { issue_state, type IssueState } from '#scripts/issue/issue-state'
+import { session_cite } from '#scripts/issue/session-cite'
+import { PROCESS_ALIVE, PROCESS_NONE, type ProcessTrace } from '#scripts/run/run-liveness'
+import { lane_await } from './lane-await'
+import type { LaneInfo } from './lane-registry'
+import { lane_spent } from './lane-spent'
+import {
+	lane_state,
+	type LaneChange,
+	type LaneRecords,
+	type LaneState,
+	type RecordOutcome,
+} from './lane-state'
+
+// `josh lane:adopt` (joshuafolkken/kit#4744): give a lane whose state record was lost — a restart, a
+// usage limit, an interrupted run — a record again, from what can be read off it, without touching its
+// branch, its work tree or its pull request.
+//
+// **Nothing is guessed.** A lane is written `open` — opened, no child working in it — only when its
+// process probe answers that no child is there and its work tree status, its unpushed commits, its pull
+// request and its issue all read; any one unread leaves it unknown, counted in use as before
+// (`backlog-occupied.ts`). `open` rather than `paused`: nobody suspended it, and a paused lane is one
+// `run:liveness` says not to recover. The next launch moves it to `running` (`lane-state.ts`), and
+// the next `backlogrun` takes the lane back while its issue still carries `in-progress`
+// (`backlog-drive-carried.ts`).
+
+const ADOPT_COMMAND = 'lane:adopt'
+const ISSUE_FIELDS = 'state,labels'
+const SEPARATOR = ' · '
+
+// The branch's pull request — the open one, else the newest (`git_gh_pr_rest.select_pull`) — with its
+// gh state, since a reopened lane's branch can still carry the merged one.
+interface Pull {
+	number: number
+	state: string
+}
+
+// A pull request read: the branch's pull request, or none.
+interface PullRead {
+	pull: Pull | undefined
+}
+
+interface LaneFacts {
+	branch: string
+	is_dirty: boolean
+	unpushed: number
+	pull: Pull | undefined
+	issue: IssueState
+}
+
+// Each read answers `undefined` when it could not be made.
+interface AdoptPorts {
+	process_trace: (issue: string) => ProcessTrace
+	tree_status: (directory: string) => Promise<string | undefined>
+	unpushed_commits: (branch: string) => Promise<number | undefined>
+	pull_request: (branch: string) => Promise<PullRead | undefined>
+	issue: (issue: string) => Promise<IssueState | undefined>
+	record: (change: LaneChange) => Promise<RecordOutcome>
+}
+
+type Adoption =
+	| { kind: 'adopted'; facts: LaneFacts }
+	| { kind: 'kept'; state: LaneState }
+	| { kind: 'left'; reason: string }
+
+async function read_tree_status(directory: string): Promise<string | undefined> {
+	try {
+		return await git_command.status(directory)
+	} catch {
+		return undefined
+	}
+}
+
+async function read_pull(branch: string): Promise<Pull | undefined> {
+	const number = await git_gh_pr_read.pr_get_number(branch)
+
+	if (number === undefined) return undefined
+
+	// The listing row carries `state` and `merged_at` too, so it stands in for a detail GitHub refuses
+	// as too many files changed.
+	const pull = await read_pull_or_listed(branch, number, read_rest_pull)
+	const state = git_gh_pr_rest.to_pr_state(pull)
+
+	return state === undefined ? undefined : { number, state }
+}
+
+// `undefined` when anything could not be read, including a pull request that exists but whose number
+// or state did not resolve.
+async function read_pull_request(branch: string): Promise<PullRead | undefined> {
+	try {
+		if (!(await git_gh_pr_read.pr_exists(branch))) return { pull: undefined }
+
+		const pull = await read_pull(branch)
+
+		return pull === undefined ? undefined : { pull }
+	} catch {
+		return undefined
+	}
+}
+
+async function read_issue(issue: string): Promise<IssueState | undefined> {
+	const json = await git_gh_issue_read.issue_view_json(issue, ISSUE_FIELDS)
+
+	return json === undefined ? undefined : issue_state.parse_issue_state(json)
+}
+
+async function record_open(change: LaneChange): Promise<RecordOutcome> {
+	return await lane_state.record_adopted(change)
+}
+
+const LIVE_PORTS: AdoptPorts = {
+	process_trace: lane_await.process_trace_default,
+	tree_status: read_tree_status,
+	unpushed_commits: lane_spent.read_unpushed_commits,
+	pull_request: read_pull_request,
+	issue: read_issue,
+	record: record_open,
+}
+
+function left(reason: string): Adoption {
+	return { kind: 'left', reason }
+}
+
+function process_reason(lane: LaneInfo, ports: AdoptPorts): string | undefined {
+	if (lane.is_stranded) return 'its work tree is gone'
+
+	const trace = ports.process_trace(lane.issue)
+
+	if (trace === PROCESS_ALIVE) return 'a child is working in it'
+
+	return trace === PROCESS_NONE ? undefined : 'its process probe did not answer'
+}
+
+// What each fact is called where it could not be read, in the order `facts_of` reads them.
+const FACT_NAMES = ['work tree status', 'unpushed commits', 'pull request', 'issue'] as const
+
+function unread_names(reads: ReadonlyArray<unknown>): string {
+	return FACT_NAMES.filter((_name, index) => reads[index] === undefined).join(', ')
+}
+
+async function facts_of(lane: LaneInfo, ports: AdoptPorts): Promise<LaneFacts | string> {
+	const reads = await Promise.all([
+		ports.tree_status(lane.directory),
+		ports.unpushed_commits(lane.branch),
+		ports.pull_request(lane.branch),
+		ports.issue(lane.issue),
+	])
+	const [status, unpushed, pull, issue] = reads
+
+	if (status === undefined || unpushed === undefined || pull === undefined || issue === undefined) {
+		return `could not read its ${unread_names(reads)}`
+	}
+
+	return { branch: lane.branch, is_dirty: status.trim() !== '', unpushed, pull: pull.pull, issue }
+}
+
+async function written(issue: string, facts: LaneFacts, ports: AdoptPorts): Promise<Adoption> {
+	const outcome = await ports.record({ issue, state: 'open', command: ADOPT_COMMAND })
+
+	return outcome.kind === 'written' ? { kind: 'adopted', facts } : left(outcome.reason)
+}
+
+/** Write an `open` record for `lane` when it has none and every fact about it reads. */
+async function adopt(
+	lane: LaneInfo,
+	records: LaneRecords,
+	ports: AdoptPorts = LIVE_PORTS,
+): Promise<Adoption> {
+	const recorded = records.get(lane.issue)
+
+	if (recorded !== undefined) return { kind: 'kept', state: recorded.state }
+
+	const blocked = process_reason(lane, ports)
+
+	if (blocked !== undefined) return left(blocked)
+
+	const facts = await facts_of(lane, ports)
+
+	return typeof facts === 'string' ? left(facts) : await written(lane.issue, facts, ports)
+}
+
+/** `branch 4744-lane · uncommitted changes · 2 unpushed commit(s) · PR [#4801](…) OPEN · issue OPEN (in-progress)` */
+function facts_text(facts: LaneFacts): string {
+	const labels = facts.issue.labels.length > 0 ? ` (${facts.issue.labels.join(', ')})` : ''
+
+	return [
+		`branch ${facts.branch}`,
+		facts.is_dirty ? 'uncommitted changes' : 'clean tree',
+		`${String(facts.unpushed)} unpushed commit(s)`,
+		facts.pull === undefined
+			? 'no PR'
+			: `PR ${session_cite.issue(facts.pull.number)} ${facts.pull.state}`,
+		`issue ${facts.issue.state}${labels}`,
+	].join(SEPARATOR)
+}
+
+const lane_adopt = { ADOPT_COMMAND, adopt, facts_text, read_pull_request }
+
+export { lane_adopt }
+export type { AdoptPorts, Adoption, LaneFacts }

package/scripts/lane/lane-await.ts

@@ -2,6 +2,7 @@ import { spawnSync } from 'node:child_process'
 import { setTimeout as sleep } from 'node:timers/promises'
 import { parseArgs } from 'node:util'
 import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { poll } from '#scripts/lib/poll'
 import { MS_PER_SECOND, PROBE_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import {
 	PROCESS_ALIVE,
@@ -290,14 +291,10 @@ async function wait_for_any(
 	const config = resolve_options(options)
 	const states = await make_states(issues, config.is_settled)
 
-	for (;;) {
-		const completed = check_any(states, config.now(), config)
-
-		if (completed !== undefined) return completed
-
-		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
-		await config.sleep(config.poll_ms)
-	}
+	return await poll.wait_for(() => check_any(states, config.now(), config), {
+		interval_ms: config.poll_ms,
+		sleeper: config.sleep,
+	})
 }
 
 const lane_await = {

package/scripts/lane/lane-baseline.ts

@@ -0,0 +1,123 @@
+import { detached_launch } from '#scripts/run/detached-launch'
+import { run_event_baseline } from '#scripts/run/event/run-event-baseline'
+import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-stream'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
+import { lane_investigation_switch } from './lane-investigation-switch'
+import { lane_ledger } from './lane-ledger'
+import { lane_overrun } from './lane-overrun'
+import { lane_overrun_prompt } from './lane-overrun-prompt'
+import { lane_stage_stats } from './lane-stage-stats'
+
+// Every `BASELINE_MERGES`-th merge the median lane itself is investigated (joshuafolkken/kit#4887).
+// The overrun investigation (`lane-overrun.ts`) reads only a lane slower than the threshold, so the time
+// every lane spends is never a candidate for a cut. `run:merge` asks at each merge: the last multiple the
+// ledger's merge count reached, when no note has it yet, launches a detached worker session that reads
+// `lane:stats`, takes the stages and sub-stages that spend the most per merge, and files their causes
+// by the overrun investigation's filing rules — the same prompt part, a cause's reducible minutes cut
+// from one median merge rather than one lane (joshuafolkken/kit#4928). Its filings name no lane they
+// were found during. The launch and the session's result go on the run's event stream as notes, which
+// `run:board` shows. It runs only while `JOSH_LANE_INVESTIGATION` is on (`lane-investigation-switch.ts`);
+// off by default, a due bucket launches nothing and notes nothing (joshuafolkken/kit#5044).
+
+const { EVENT_KIND } = run_event_stream
+const BASELINE_MERGES = 30
+const LOG_PREFIX = 'josh-lane-baseline-'
+const STATS_PERIOD_DAYS = 3
+const MEDIAN_PLACEHOLDER = '<median lane minutes>'
+const SCOPE = 'the median merge, judged from the per-merge minutes `lane:stats` prints'
+
+// The last multiple of `BASELINE_MERGES` the count reached: two merges recorded between two asks, or an
+// ask that failed, still leave the bucket due at the next merge.
+function due_bucket(merges: number): number {
+	return Math.floor(merges / BASELINE_MERGES) * BASELINE_MERGES
+}
+
+// A count investigated already — a retried merge finds its note — launches no second session. A
+// failure names no count, so it never answers for one.
+function is_noted(events: ReadonlyArray<RunEvent>, merges: number): boolean {
+	return events.some((event) => {
+		const note = event.kind === EVENT_KIND.NOTE ? run_event_baseline.parse(event.text) : undefined
+
+		return note !== undefined && note.kind !== 'failed' && note.merges === merges
+	})
+}
+
+// The due bucket of the ledger's merge count, else `undefined` before the first.
+async function due_merges(): Promise<number | undefined> {
+	const path = await lane_ledger.target()
+
+	if (path === undefined) return undefined
+
+	const merges = lane_ledger.read_entries(path).filter((entry) => lane_stage_stats.is_merge(entry))
+	const bucket = due_bucket(merges.length)
+
+	return bucket > 0 ? bucket : undefined
+}
+
+function reading(merges: number): string {
+	return [
+		`Investigate the median lane after ${String(merges)} merges: not an overrun, but the time every lane`,
+		'spends. Leave this checkout as it is: write any file, an issue body included, under the system temp',
+		'directory, and never stage, commit or push.',
+		`Read \`pnpm josh lane:stats --period ${String(STATS_PERIOD_DAYS)}\` — its stage table and its`,
+		'implement sub-stage table — and take the several stages and sub-stages with the largest per-merge',
+		"time, not just the one largest. Read the period lanes' transcripts (the lane directories `lane:stats`",
+		"reads) and the run events (`pnpm josh run:event --from 0`) for where each one's time goes, and find",
+		'the causes a fix could cut.',
+		'Trace each cause to what can fix it: the minutes it spends per merge, the signal that led to the',
+		'spend (which command printed what), the `file:line` of the code or document that decided it, and',
+		'where to fix it.',
+	].join(' ')
+}
+
+// One line: `detached_launch` lets a prompt break lines, but a single line keeps the log header whole.
+function prompt(issue: number, merges: number): string {
+	const handling = lane_overrun_prompt.cause_handling({
+		origin: undefined,
+		loss_lines: lane_overrun_prompt.loss_lines_of(issue, MEDIAN_PLACEHOLDER),
+		template: run_event_baseline.ended_text(merges, '<result>'),
+		scope: SCOPE,
+	})
+
+	return `${reading(merges)} ${handling}`
+}
+
+function note_failure(note: string): void {
+	void run_event_stream_emit.emit(EVENT_KIND.NOTE, run_event_baseline.failed_text(note))
+}
+
+// The launch at merge `issue`, the `merges`-th; its filings count against that lane.
+function launched(issue: number, merges: number): string {
+	return lane_overrun.launch({
+		env: {},
+		prompt: prompt(issue, merges),
+		log_prefix: `${LOG_PREFIX}${String(merges)}-`,
+		on_failure: note_failure,
+	})
+}
+
+async function investigate_baseline(issue: number): Promise<void> {
+	const merges = await due_merges()
+
+	if (merges === undefined || is_noted(await run_event_stream_emit.all_events(), merges)) return
+
+	await run_event_stream_emit.emit(
+		EVENT_KIND.NOTE,
+		run_event_baseline.started_text(merges, launched(issue, merges)),
+	)
+}
+
+// Never fails the merge it follows: an error is a note on the stream, not a refused merge.
+async function investigate(issue: number): Promise<void> {
+	if (!lane_investigation_switch.is_on()) return
+
+	try {
+		await investigate_baseline(issue)
+	} catch (error) {
+		note_failure(detached_launch.note_of(error))
+	}
+}
+
+const lane_baseline = { due_bucket, investigate }
+
+export { lane_baseline }

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

@@ -0,0 +1,64 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { session_cite } from '#scripts/issue/session-cite'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
+import { lane_breakdown } from './lane-breakdown'
+import { lane_breakdown_text } from './lane-breakdown-text'
+import { lane_ledger } from './lane-ledger'
+import { lane_net_time } from './lane-net-time'
+
+// `josh lane:breakdown <issue>` — a merged lane's net time by stage (joshuafolkken/kit#4995), the same
+// breakdown its overrun investigation comments on its Issue.
+
+const ARGV_OFFSET = 2
+const FAILURE_EXIT_CODE = 1
+const USAGE = 'Usage: josh lane:breakdown <issue>'
+
+async function read_ledger(): Promise<ReturnType<typeof lane_ledger.read_entries>> {
+	const path = await lane_ledger.target()
+
+	return path === undefined ? [] : lane_ledger.read_entries(path)
+}
+
+function missing(issue: string): number {
+	const lane = session_cite.issue(issue)
+
+	console.error(`josh lane:breakdown ${issue}: the ledger holds no dispatch and merge of ${lane}`)
+
+	return FAILURE_EXIT_CODE
+}
+
+async function print(issue: string): Promise<number> {
+	const [entries, events] = [await read_ledger(), await run_event_stream_emit.all_events()]
+	const minutes = lane_net_time.net_minutes(entries, events, Number(issue))
+	const breakdown = lane_breakdown.of(entries, events, Number(issue))
+
+	if (minutes === undefined || breakdown === undefined) return missing(issue)
+
+	const report = lane_breakdown_text.report_of(Number(issue), breakdown, entries)
+
+	console.info(lane_breakdown_text.comment(Number(issue), minutes, report))
+
+	return 0
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const [issue = ''] = argv
+
+	if (argv.length === 1 && issue_number_shape.is_issue_number(issue)) return await print(issue)
+
+	console.error(USAGE)
+
+	return FAILURE_EXIT_CODE
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const lane_breakdown_cli = { USAGE, run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { lane_breakdown_cli }

package/scripts/lane/lane-breakdown-implement.ts

@@ -0,0 +1,170 @@
+import { cost_transcript } from '#scripts/cost-runtime/cost-transcript'
+import { lane_breakdown, type Breakdown, type Stage } from './lane-breakdown'
+import type { LaneSpan } from './lane-net-time'
+import type { Subagent, ToolCall } from './lane-transcript-calls'
+import { lane_transcript_stats } from './lane-transcript-stats'
+
+// The implementation stage of a lane's breakdown (joshuafolkken/kit#4995) split by what its tool calls
+// spent, read off the lane's transcripts: the main josh commands, the subagents, the reads and the rest
+// of Bash, and what no call spent — the edits and the thinking. A backgrounded call has no duration
+// (`lane-transcript-calls.ts`), so the wait on its result falls in the remainder; only its count shows.
+//
+// **The subagents split by the agent dispatched** — `subagent: investigator`, `subagent: reviewer`, …
+// — and a backgrounded subagent call still names its kind, at no time, with its count beside it
+// (joshuafolkken/kit#5297). `run:review` and `ship` / `ship:wait` count apart from other bash
+// (joshuafolkken/kit#5293).
+
+const REMAINDER = 'editing & thinking'
+const OTHER_BASH = 'other bash'
+const BASH_TOOL = 'Bash'
+const READ = 'read'
+
+const TOOL_KINDS: ReadonlyMap<string, string> = new Map([
+	['Read', READ],
+	['Grep', READ],
+	['Glob', READ],
+])
+
+const COMMAND_KINDS: ReadonlyArray<readonly [RegExp, string]> = [
+	[/\bjosh main:merge\b/u, 'main:merge'],
+	[/\bjosh check:related\b/u, 'check:related'],
+	[/\bjosh gate\b/u, 'gate'],
+	[/\bjosh run:review\b/u, 'run:review'],
+	[/\bjosh ship(?::wait)?\b/u, 'ship / ship:wait'],
+	[/\bjosh test(?::[\w-]+)?\b/u, 'test'],
+	[/\bjosh (?:lint|cspell)(?::[\w-]+)?\b/u, 'lint / cspell'],
+]
+
+interface ImplementDetail {
+	// Longest first, the remainder among them.
+	kinds: ReadonlyArray<Stage>
+	// The calls backgrounded inside the implementation.
+	background: number
+	// Each subagent kind's backgrounded calls, counted at no time.
+	untimed: ReadonlyMap<string, number>
+}
+
+function command_kind(command: string): string {
+	return COMMAND_KINDS.find(([pattern]) => pattern.test(command))?.[1] ?? OTHER_BASH
+}
+
+function subagent_kind(subagent: Subagent): string {
+	return `subagent: ${subagent.type}`
+}
+
+// The kind a call counts under, `undefined` for one that falls in the remainder (an edit included).
+function kind_of(call: ToolCall): string | undefined {
+	if (call.tool === BASH_TOOL) return command_kind(call.command ?? '')
+	if (call.subagent !== undefined) return subagent_kind(call.subagent)
+
+	return TOOL_KINDS.get(call.tool ?? '')
+}
+
+interface TimedPart extends Stage {
+	from_ms: number
+}
+
+function is_untimed_subagent(call: ToolCall): boolean {
+	return call.background && call.subagent !== undefined
+}
+
+// A call's own milliseconds, cut at the end of the span it started in; a backgrounded subagent call's none.
+function timed_part(call: ToolCall, span: LaneSpan): ReadonlyArray<TimedPart> {
+	const name = kind_of(call)
+
+	if (name === undefined) return []
+
+	const ms = Math.min(call.duration_ms ?? 0, span.to_ms - call.started_ms)
+	const is_counted = call.duration_ms !== undefined || is_untimed_subagent(call)
+
+	return is_counted ? [{ name, ms, from_ms: call.started_ms }] : []
+}
+
+function untimed_of(placed: ReadonlyArray<readonly [ToolCall, LaneSpan]>): Map<string, number> {
+	const counts = new Map<string, number>()
+	const kinds = placed.filter(([call]) => is_untimed_subagent(call)).map(([call]) => kind_of(call))
+
+	for (const kind of kinds) if (kind !== undefined) counts.set(kind, (counts.get(kind) ?? 0) + 1)
+
+	return counts
+}
+
+// What neither a timed call nor a wait covers of the implementation's spans, each millisecond once.
+function remainder_ms(parts: ReadonlyArray<TimedPart>, breakdown: Breakdown): number {
+	const busy = parts.map((part) => ({ from_ms: part.from_ms, to_ms: part.from_ms + part.ms }))
+	const covering = [...busy, ...breakdown.waits]
+	const idle = breakdown.implement.map(
+		(span) => span.to_ms - span.from_ms - lane_breakdown.covered_ms(span, covering),
+	)
+
+	return idle.reduce((sum, ms) => sum + ms, 0)
+}
+
+function span_of(call: ToolCall, spans: ReadonlyArray<LaneSpan>): LaneSpan | undefined {
+	return spans.find((span) => call.started_ms >= span.from_ms && call.started_ms < span.to_ms)
+}
+
+function placed_of(
+	calls: ReadonlyArray<ToolCall>,
+	spans: ReadonlyArray<LaneSpan>,
+): Array<readonly [ToolCall, LaneSpan]> {
+	return calls.flatMap((call) => {
+		const span = span_of(call, spans)
+
+		return span === undefined ? [] : [[call, span] as const]
+	})
+}
+
+// The implementation split by the calls made inside it — parallel calls each count their own time, so
+// the kinds can add up to more — and the remainder, the time no call and no wait covered.
+function of(calls: ReadonlyArray<ToolCall>, breakdown: Breakdown): ImplementDetail {
+	const placed = placed_of(calls, breakdown.implement)
+	const parts = placed.flatMap(([call, span]) => timed_part(call, span))
+	const remainder = { name: REMAINDER, ms: remainder_ms(parts, breakdown) }
+
+	return {
+		kinds: lane_breakdown.ranked([...parts, remainder]),
+		background: placed.filter(([call]) => call.background).length,
+		untimed: untimed_of(placed),
+	}
+}
+
+// The Bash calls started inside `spans`, by the implementation's kinds — the fixes, re-ships and checks
+// a lane child ran between two ship stages (joshuafolkken/kit#5294).
+function bash_kinds(calls: ReadonlyArray<ToolCall>, spans: ReadonlyArray<LaneSpan>): Array<Stage> {
+	const placed = placed_of(
+		calls.filter((call) => call.tool === BASH_TOOL),
+		spans,
+	)
+
+	return lane_breakdown.ranked(placed.flatMap(([call, span]) => timed_part(call, span)))
+}
+
+// The lane's own transcript directories — `<lane root slug>-<issue>` under `~/.claude/projects`.
+function transcript_directories(issue: number): ReadonlyArray<string> {
+	const main_cwd = cost_transcript.session_cwd(process.cwd())
+	const home = cost_transcript.home_directory()
+	const suffix = `-${String(issue)}`
+
+	return cost_transcript
+		.lane_transcript_directories(main_cwd, home)
+		.filter((directory) => directory.endsWith(suffix))
+}
+
+// The tool calls of `issue`'s lane sessions still written to once its implementation began, up to the
+// end of its last ship stage.
+function read(issue: number, breakdown: Breakdown): Array<ToolCall> {
+	const [first] = breakdown.implement
+	const last = breakdown.ship.at(-1) ?? breakdown.implement.at(-1)
+
+	if (first === undefined || last === undefined) return []
+
+	const window = { since_ms: first.from_ms, until_ms: last.to_ms }
+
+	return lane_transcript_stats.read_calls(transcript_directories(issue), window)
+}
+
+const lane_breakdown_implement = { bash_kinds, of, read, transcript_directories }
+
+export { lane_breakdown_implement }
+export type { ImplementDetail }