@joshuafolkken/kit 1.2116.0 → 1.3041.0

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

@@ -11,7 +11,7 @@ import { lane_transcript_stats } from './lane-transcript-stats'
 // earlier calls to its own, the model's turn before it included — is put to one sub-stage, and `lane:stats` prints each one's
 // median over the period's lanes.
 //
-// **A lane's implement ends at its first `josh ship` call**, so a lane that never shipped in the period
+// **A lane's implement ends at its first `ship` or `run:chain --join --ship` call**, so a lane that never shipped in the period
 // has no implement here. **`review-fix` runs from `run:review` on** — the round's fixes and their scoped
 // checks; before it, an edit is `edit`, a scoped check or gate is `check`, and any other call is `plan`
 // before the first edit, `read` after it. **A session's first call spans its own duration**, so the gap
@@ -23,19 +23,24 @@ const SUB_STAGES = ['plan', 'read', 'edit', 'check', 'review-fix'] as const
 type SubStage = (typeof SUB_STAGES)[number]
 const [PLAN, READ, EDIT, CHECK, REVIEW_FIX] = SUB_STAGES
 type Totals = ReadonlyMap<SubStage, number>
+const LINT_RELATED = 'lint:related'
 
 const EDIT_TOOLS: ReadonlySet<string> = new Set(['Edit', 'MultiEdit', 'NotebookEdit', 'Write'])
 const CHECK_COMMANDS: ReadonlySet<string> = new Set([
 	'check:related',
 	'cspell:dot',
 	'gate',
-	'lint:related',
+	LINT_RELATED,
 	'metrics',
 	'test:pinned',
 	'test:related',
 ])
 const REVIEW_COMMANDS: ReadonlySet<string> = new Set(['review:brief', 'run:review'])
 const SHIP_COMMANDS: ReadonlySet<string> = new Set(['ship'])
+const JOIN_FLAG = /\s--join(?:\s|$)/u
+const SHIP_FLAG = /\s--ship(?:\s|=|$)/u
+const CHAIN_REACHED_SHIP = /^run:chain \d+ — (?:ran (?:[^\s]+ → )*ship$|stopped at ship \()/mu
+const FIRST_LINT_ROW = `lane first ${LINT_RELATED}`
 // `backgrounded` counts a subagent row's untimed calls (`lane-implement-subagents.ts`); a sub-stage has none.
 const COLUMNS = [
 	'implement sub-stage',
@@ -106,26 +111,65 @@ function active_ms(call: ToolCall, reach: Reach, paused: ReadonlyArray<PausedSpa
 	return span - lane_paused_spans.overlap_ms(paused, end - span, end)
 }
 
-// Each sub-stage's summed span over one lane's implement calls, oldest first.
-function lane_totals(calls: ReadonlyArray<ToolCall>, paused: ReadonlyArray<PausedSpan>): Totals {
-	const totals = new Map<SubStage, number>(SUB_STAGES.map((stage) => [stage, 0]))
+// One implement call with the sub-stage its span went to and that span less its paused overlap.
+interface StagedCall {
+	call: ToolCall
+	stage: SubStage
+	active_ms: number
+}
+
+// One lane's implement calls, oldest first, each put to its sub-stage.
+function staged(
+	calls: ReadonlyArray<ToolCall>,
+	paused: ReadonlyArray<PausedSpan>,
+): Array<StagedCall> {
+	const result: Array<StagedCall> = []
 	let phase: Phase = { edited: false, reviewing: false }
 	let reach = NO_REACH
 
 	for (const call of calls) {
 		phase = next_phase(call, phase)
-		const stage = sub_stage_of(call, phase)
-
-		totals.set(stage, (totals.get(stage) ?? 0) + active_ms(call, reach, paused))
+		result.push({
+			call,
+			stage: sub_stage_of(call, phase),
+			active_ms: active_ms(call, reach, paused),
+		})
 		reach = next_reach(call, reach)
 	}
 
+	return result
+}
+
+// Each sub-stage's summed span over one lane's implement calls, oldest first.
+function lane_totals(calls: ReadonlyArray<ToolCall>, paused: ReadonlyArray<PausedSpan>): Totals {
+	const totals = new Map<SubStage, number>(SUB_STAGES.map((stage) => [stage, 0]))
+
+	for (const entry of staged(calls, paused)) {
+		totals.set(entry.stage, (totals.get(entry.stage) ?? 0) + entry.active_ms)
+	}
+
 	return totals
 }
 
-// One lane's calls before its first ship, or `undefined` when it never shipped.
+function chain_ships(segment: string): boolean {
+	return (
+		lane_transcript_stats.josh_commands(segment).includes('run:chain') &&
+		JOIN_FLAG.test(segment) &&
+		SHIP_FLAG.test(segment)
+	)
+}
+
+function starts_ship(call: ToolCall): boolean {
+	return (
+		runs_any(call, SHIP_COMMANDS) ||
+		(CHAIN_REACHED_SHIP.test(call.output) &&
+			lane_transcript_stats.command_segments(call.command).some((segment) => chain_ships(segment)))
+	)
+}
+
+// One lane's calls before its first ship, including the clean join's ship option.
 function implement_calls(calls: ReadonlyArray<ToolCall>): ReadonlyArray<ToolCall> | undefined {
-	const ship = calls.findIndex((call) => runs_any(call, SHIP_COMMANDS))
+	const ship = calls.findIndex((call) => starts_ship(call))
 
 	return ship === -1 ? undefined : calls.slice(0, ship)
 }
@@ -171,11 +215,9 @@ function lane_totals_in(
 	return implement_lanes(calls, window, paused).map((lane) => lane_totals(lane.calls, lane.paused))
 }
 
-function stage_row(stage: SubStage, totals: ReadonlyArray<Totals>): Array<string> {
-	const values = totals.map((lane) => lane.get(stage) ?? 0)
-
+function minutes_row(label: string, values: ReadonlyArray<number>): Array<string> {
 	return [
-		stage,
+		label,
 		String(values.length),
 		lane_stage_stats.cell(lane_stats.median(values)),
 		lane_stage_stats.cell(lane_stats.peak(values)),
@@ -183,14 +225,40 @@ function stage_row(stage: SubStage, totals: ReadonlyArray<Totals>): Array<string
 	]
 }
 
+function stage_row(stage: SubStage, totals: ReadonlyArray<Totals>): Array<string> {
+	return minutes_row(
+		stage,
+		totals.map((lane) => lane.get(stage) ?? 0),
+	)
+}
+
+// One lane's first timed solo `lint:related` less its paused overlap, or `undefined` when it ran none; a
+// backgrounded call, or one whose session ended before its result, has no duration to count, and a
+// chained call's duration holds its other commands too (joshuafolkken/kit#5785).
+function first_lint_ms(lane: ImplementLane): number | undefined {
+	const first = lane_transcript_stats
+		.solo_calls(lane.calls, LINT_RELATED)
+		.find((call) => call.duration_ms !== undefined)
+
+	return first === undefined ? undefined : active_ms(first, NO_REACH, lane.paused)
+}
+
+// How many lanes a cold first `lint:related` held up (joshuafolkken/kit#5714); no row when none ran one.
+function first_lint_rows(lanes: ReadonlyArray<ImplementLane>): Array<Array<string>> {
+	const values = lanes.flatMap((lane) => first_lint_ms(lane) ?? [])
+
+	return values.length === 0 ? [] : [minutes_row(FIRST_LINT_ROW, values)]
+}
+
 // The period's table: `calls` is every lane session's calls, filtered here to `window`; `paused` is
-// each lane's paused spans (`lane-paused-spans.ts`). The sub-stages, then the subagents by agent type
-// (`lane-implement-subagents.ts`).
+// each lane's paused spans (`lane-paused-spans.ts`). The sub-stages, the lane first `lint:related` row,
+// then the subagents by agent type (`lane-implement-subagents.ts`).
 function table(calls: ReadonlyArray<ToolCall>, window: StatsWindow, paused: PausedSpans): string {
 	const lanes = implement_lanes(calls, window, paused)
 	const totals = lanes.map((lane) => lane_totals(lane.calls, lane.paused))
 	const rows = [
 		...SUB_STAGES.map((stage) => stage_row(stage, totals)),
+		...first_lint_rows(lanes),
 		...lane_implement_subagents.rows(lanes),
 	]
 
@@ -201,7 +269,14 @@ function table(calls: ReadonlyArray<ToolCall>, window: StatsWindow, paused: Paus
 	].join('\n')
 }
 
-const lane_implement_stats = { SUB_STAGES, lane_totals_in, table }
+const lane_implement_stats = {
+	EDIT_TOOLS,
+	SUB_STAGES,
+	implement_lanes,
+	lane_totals_in,
+	staged,
+	table,
+}
 
-export type { SubStage }
+export type { StagedCall, SubStage }
 export { lane_implement_stats }

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

@@ -0,0 +1,61 @@
+import { core_budget, type Handle, type ReserveOptions } from '#scripts/gate/core-budget'
+import { core_wait } from '#scripts/gate/core-wait'
+import type { LaunchContext, LaunchOutcome } from './lane-launch-cli'
+import { lane_paths } from './lane-paths'
+
+// Reserve one lane's share of the claude RSS peak `lane:stats` measured once the gate
+// reservations were honest (#6684): the peak summed over every claude process, divided by the
+// effective lanes plus the driver session. Reviewer / investigator subagents run inside the
+// parent process, so that sum already holds them (joshuafolkken/kit#5409, #6229, #6685).
+const LANE_MEMORY_MB = 470
+
+function checkout_of(issue: string): string {
+	const cwd = process.cwd()
+	const root = core_wait.where_of(cwd).lanes_root ?? lane_paths.lane_root(cwd)
+
+	return lane_paths.lane_directory(root, issue)
+}
+
+function options_of(issue: string): ReserveOptions {
+	return {
+		memory_mb: LANE_MEMORY_MB,
+		is_strict_admission: true,
+		is_memory_pending: true,
+		command: 'lane:launch',
+		checkout: checkout_of(issue),
+	}
+}
+
+async function run_reserved(
+	context: LaunchContext,
+	run: (context: LaunchContext) => Promise<LaunchOutcome>,
+	handle: Handle,
+): Promise<LaunchOutcome> {
+	let is_retained = false
+
+	try {
+		const outcome = await run(context)
+
+		if (outcome.kind === 'launched') {
+			core_budget.transfer(handle, Number(outcome.pid))
+			is_retained = true
+		}
+
+		return outcome
+	} finally {
+		if (!is_retained) core_budget.release(handle)
+	}
+}
+
+async function launch(
+	context: LaunchContext,
+	run: (context: LaunchContext) => Promise<LaunchOutcome>,
+): Promise<LaunchOutcome> {
+	const handle = await core_budget.reserve(0, options_of(context.issue))
+
+	return await run_reserved(context, run, handle)
+}
+
+const lane_launch_admission = { launch, options_of, run_reserved }
+
+export { lane_launch_admission }

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

@@ -1,11 +1,13 @@
 import { issue_number_shape } from '#scripts/issue/issue-number-shape'
-import { josh_command } from '#scripts/josh/josh-run'
+import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
 import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
 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 { execa } from 'execa'
+import { lane_launch_admission } from './lane-launch-admission'
+import { lane_launch_pending } from './lane-launch-pending'
 
 // `josh lane:launch <issue> [--stash <message>]` — one composite command for a `backlogrun` lane-start
 // event. Opening one lane was four to six turns of the parent: `lane:open`,
@@ -28,6 +30,8 @@ const USAGE = 'Usage: josh lane:launch <issue-number> [--stash <message>]'
 
 const OPTIONS = { stash: { type: 'string' } } as const
 
+const PREPARED: JoshResult = { code: SUCCESS_EXIT_CODE, out: '' }
+
 // The stash message is present only for the first lane — the caller passes `--stash` there and nowhere
 // else, so "only the first lane pops and re-installs" is preserved by which invocation carries it.
 interface LaunchContext {
@@ -53,50 +57,66 @@ function read_context(argv: ReadonlyArray<string>): LaunchContext | undefined {
 	return { issue, stash: parsed.values.stash }
 }
 
+// Where the chain ended. `unopened` is a `lane:open` refusal — no lane was taken; `failed` is a step
+// after it, which leaves the opened lane holding a seat, so a caller cannot read the two alike. Either
+// carries the failing step's own explanation as `detail`, when it said one.
+type Refusal = { kind: 'unopened'; detail?: string } | { kind: 'failed'; detail?: string }
+
+type LaunchOutcome = Refusal | { kind: 'launched'; pid: string } | { kind: 'waiting' }
+
+// The step's stderr, or its stdout when stderr is empty; nothing when it said neither.
+function failure_detail(result: JoshResult): string | undefined {
+	const detail = (result.err ?? '').trim() || result.out.trim()
+
+	return detail === '' ? undefined : detail
+}
+
+function refused(kind: Refusal['kind'], result: JoshResult): Refusal {
+	const detail = failure_detail(result)
+
+	return detail === undefined ? { kind } : { kind, detail }
+}
+
 // The pop brought in the `pnpm-lock.yaml` `josh latest` rewrote, so this one lane installs a second
 // time against it. Output is captured and surfaced only on failure, so the composite's stdout stays
 // the child's pid alone.
-async function install(directory: string): Promise<boolean> {
+async function install(directory: string): Promise<JoshResult> {
 	const result = await execa(PNPM, ['--dir', directory, 'install', '--frozen-lockfile'], {
 		reject: false,
 		timeout: INSTALL_TIMEOUT_MS,
 	})
+	const installed = {
+		code: result.exitCode ?? FAILURE_EXIT_CODE,
+		out: result.stdout,
+		err: result.stderr,
+	}
 
-	if ((result.exitCode ?? FAILURE_EXIT_CODE) === SUCCESS_EXIT_CODE) return true
-
-	console.error(result.stderr === '' ? result.stdout : result.stderr)
+	if (installed.code !== SUCCESS_EXIT_CODE) console.error(failure_detail(installed) ?? '')
 
-	return false
+	return installed
 }
 
 // The first lane pops the shared stash and re-installs against the lock it brought in; a pop that
 // refused (`no-match` / `ambiguous`) stops the lane rather than dispatching onto an unprepared tree.
 // A caller without `--stash` skips both, which is every lane after the first. The re-install is a
 // stage of its own on the run's stream, as the install `lane:open` ran was.
-async function prepare(context: LaunchContext, directory: string): Promise<boolean> {
+async function prepare(context: LaunchContext, directory: string): Promise<JoshResult> {
 	const { issue, stash } = context
 
-	if (stash === undefined) return true
+	if (stash === undefined) return PREPARED
 
 	const popped = await josh_command.josh_run(
 		['stash:pop', stash, '--dir', directory],
 		should_forward_stderr,
 	)
 
-	if (popped.code !== SUCCESS_EXIT_CODE) return false
+	if (popped.code !== SUCCESS_EXIT_CODE) return popped
 
 	await run_event_setup.emit(run_event_setup.installing(issue))
 
 	return await install(directory)
 }
 
-// Where the chain ended. `unopened` is a `lane:open` refusal — no lane was taken; `failed` is a step
-// after it, which leaves the opened lane holding a seat, so a caller cannot read the two alike.
-type LaunchOutcome = { kind: 'launched'; pid: string } | { kind: 'unopened' } | { kind: 'failed' }
-
-const UNOPENED: LaunchOutcome = { kind: 'unopened' }
-const FAILED: LaunchOutcome = { kind: 'failed' }
-
 async function close_if_vacant(lane: LaneInfo | undefined): Promise<void> {
 	if (lane === undefined || !(await lane_vacant.is_vacant(lane))) return
 
@@ -114,27 +134,27 @@ async function close_if_vacant(lane: LaneInfo | undefined): Promise<void> {
 // — a run cut between the open and the dispatch leaves one. It is reopened
 // rather than reused because nothing recorded whether its install finished. A lane with work or a live
 // process in it still meets `lane:open`'s refusal.
-async function lane_directory(issue: string): Promise<string | undefined> {
+async function lane_directory(issue: string): Promise<JoshResult> {
 	const kept = await lane_registry.find_open_lane(issue)
 
-	if (kept?.output !== undefined) return kept.directory
+	if (kept?.output !== undefined) return { code: SUCCESS_EXIT_CODE, out: kept.directory }
 
 	await close_if_vacant(kept)
 
-	const opened = await josh_command.josh_run(['lane:open', issue], should_forward_stderr)
-
-	return opened.code === SUCCESS_EXIT_CODE ? opened.out : undefined
+	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_lane(context: LaunchContext): Promise<LaunchOutcome> {
-	const directory = await lane_directory(context.issue)
+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)
 
-	if (directory === undefined) return UNOPENED
+	const prepared = await prepare(context, opened.out)
 
-	if (!(await prepare(context, directory))) return FAILED
+	if (prepared.code !== SUCCESS_EXIT_CODE) return refused('failed', prepared)
 
 	await run_event_setup.emit(run_event_setup.dispatching(context.issue))
 
@@ -143,7 +163,17 @@ async function launch_lane(context: LaunchContext): Promise<LaunchOutcome> {
 		should_forward_stderr,
 	)
 
-	return dispatched.code === SUCCESS_EXIT_CODE ? { kind: 'launched', pid: dispatched.out } : FAILED
+	if (dispatched.code !== SUCCESS_EXIT_CODE) return refused('failed', dispatched)
+
+	return { kind: 'launched', pid: dispatched.out }
+}
+
+async function launch_lane(context: LaunchContext): Promise<LaunchOutcome> {
+	return await lane_launch_admission.launch(context, launch_admitted)
+}
+
+async function launch_ready_lane(context: LaunchContext): Promise<LaunchOutcome> {
+	return await lane_launch_pending.launch(context, launch_admitted)
 }
 
 async function launch(context: LaunchContext): Promise<number> {
@@ -168,7 +198,13 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 	return await launch(context)
 }
 
-const lane_launch_cli = { launch_lane, read_context, run }
+const lane_launch_cli = {
+	keep_pending: lane_launch_pending.keep,
+	launch_lane,
+	launch_ready_lane,
+	read_context,
+	run,
+}
 
 export type { LaunchContext, LaunchOutcome }
 export { lane_launch_cli }

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

@@ -0,0 +1,44 @@
+import { core_budget } from '#scripts/gate/core-budget'
+import { lane_launch_admission } from './lane-launch-admission'
+import type { LaunchContext, LaunchOutcome } from './lane-launch-cli'
+
+type Claim = ReturnType<typeof core_budget.claim>
+// One waiting claim per issue: the driver launches a pass's lanes side by side
+// (joshuafolkken/kit#5519), so one issue's claim must not release another's.
+const pending = new Map<string, Claim>()
+
+function keep(issues: ReadonlyArray<string>): void {
+	for (const [issue, claim] of pending) {
+		if (issues.includes(issue)) continue
+
+		core_budget.release(claim)
+		pending.delete(issue)
+	}
+}
+
+function claim_for(issue: string): Claim {
+	const claim = pending.get(issue) ?? core_budget.claim(0, lane_launch_admission.options_of(issue))
+
+	pending.set(issue, claim)
+
+	return claim
+}
+
+// A wait is not a failed launch or a running child: the driver keeps collecting children and
+// checking its window. Only a later offered pass with room may actually open and dispatch.
+async function launch(
+	context: LaunchContext,
+	run: (context: LaunchContext) => Promise<LaunchOutcome>,
+): Promise<LaunchOutcome> {
+	const handle = await core_budget.poll_claim(claim_for(context.issue))
+
+	if (handle === undefined) return { kind: 'waiting' }
+
+	pending.delete(context.issue)
+
+	return await lane_launch_admission.run_reserved(context, run, handle)
+}
+
+const lane_launch_pending = { keep, launch }
+
+export { lane_launch_pending }

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

@@ -0,0 +1,200 @@
+import {
+	closeSync,
+	constants,
+	existsSync,
+	fstatSync,
+	openSync,
+	readSync,
+	statSync,
+	truncateSync,
+	writeSync,
+} from 'node:fs'
+import { repository_lock } from '#scripts/git/repository-lock'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { atomic_write } from '#scripts/lib/atomic-write'
+import { json_value } from '#scripts/lib/json-value'
+import { z } from 'zod'
+import { lane_ledger, type LedgerEntry } from './lane-ledger'
+import { lane_ledger_write } from './lane-ledger-write'
+import type { MeasureContext } from './lane-sampler'
+
+// The ledger's records past the retention, moved to an archive beside it (joshuafolkken/kit#7038), so
+// the ledger every lane step reads stays a few days long. **Merges stay**: they are a line per lane, and
+// the baseline counts them across all time (`lane-baseline.ts`).
+//
+// **The ledger is replaced by a rename** — the tail reader (`lane-ledger-tail.ts`) reads another inode
+// again whole. A descriptor stays open on the old ledger across the rename: bytes landing past the last
+// complete line the rotation read are carried into the replacement, and an append that opened the old
+// ledger before the rename is read back off that descriptor afterwards and carried too. The archive takes
+// its lines in one append before the ledger is replaced, and a replace that throws truncates it back: a
+// rotation cut short leaves each record in exactly one file. One rotation at a time, under a lock no
+// rotation waits on.
+//
+// The readers of a lane's history — `josh lane:stats`, the per-issue `lane:net` / `lane:why` /
+// `lane:breakdown` / `cost:audit` — read the archive before the ledger (`read_history`).
+
+const RETENTION_DAYS = 14
+const MS_PER_DAY = 86_400_000
+const LEDGER_SUFFIX_PATTERN = /\.jsonl$/u
+const ARCHIVE_SUFFIX = '-archive.jsonl'
+const LOCK_SUFFIX = '.rotate.lock'
+// The writer's own mode and flags (`lane-ledger-write.ts`), which takes one record, not lines of text.
+const LEDGER_FILE_MODE = 0o600
+const { O_APPEND, O_CREAT, O_NOFOLLOW, O_RDONLY, O_WRONLY } = constants
+// eslint-disable-next-line no-bitwise -- POSIX open flags are a bit field; `||` here would be a bug
+const APPEND_FLAGS = O_WRONLY | O_APPEND | O_CREAT | O_NOFOLLOW
+// eslint-disable-next-line no-bitwise -- POSIX open flags are a bit field; `||` here would be a bug
+const READ_FLAGS = O_RDONLY | O_NOFOLLOW
+// One claim and no wait: a rotation already holding the lock does this one's work.
+const NO_WAIT_MS = 0
+
+const { LINE_SEPARATOR } = lane_ledger_write
+const { KIND } = lane_ledger
+const record_schema = z.looseObject({ kind: z.string(), at: z.string() })
+
+type ReadContext = Pick<MeasureContext, 'ledger_path'>
+
+interface Partition {
+	readonly archived: string
+	readonly count: number
+	readonly kept: string
+}
+
+interface Move extends Partition {
+	readonly descriptor: number
+	readonly end: number
+}
+
+function archive_of(ledger: string): string {
+	return `${ledger.replace(LEDGER_SUFFIX_PATTERN, '')}${ARCHIVE_SUFFIX}`
+}
+
+// Whether a line holds a record past the cutoff; a malformed line stays, as the reader skips it anyway.
+function is_past(line: string, cutoff_ms: number): boolean {
+	const record = record_schema.safeParse(json_value.parse_or_undefined(line)).data
+
+	if (record === undefined || record.kind === KIND.MERGE) return false
+
+	return Date.parse(record.at) < cutoff_ms
+}
+
+// `text` is complete lines only.
+function partition(text: string, cutoff_ms: number): Partition {
+	const archived: Array<string> = []
+	const kept: Array<string> = []
+	const lines = text.split(LINE_SEPARATOR).slice(0, -1)
+
+	for (const line of lines) {
+		const side = is_past(line, cutoff_ms) ? archived : kept
+
+		side.push(`${line}${LINE_SEPARATOR}`)
+	}
+
+	return { archived: archived.join(''), count: archived.length, kept: kept.join('') }
+}
+
+// The bytes the descriptor's file holds past `from`.
+function bytes_past(descriptor: number, from: number): Buffer {
+	const buffer = Buffer.alloc(Math.max(fstatSync(descriptor).size - from, 0))
+	const read = readSync(descriptor, buffer, 0, buffer.length, from)
+
+	return buffer.subarray(0, read)
+}
+
+// One `O_APPEND` write to a file this account owns, never through a planted link.
+function append_text(target: string, text: Uint8Array): void {
+	const descriptor = openSync(target, APPEND_FLAGS, LEDGER_FILE_MODE)
+
+	try {
+		if (!stamp_file.is_own_regular_file(target)) {
+			throw new Error(`Not an owned regular file: ${target}`)
+		}
+
+		writeSync(descriptor, text)
+	} finally {
+		closeSync(descriptor)
+	}
+}
+
+function size_of(target: string): number {
+	return existsSync(target) ? statSync(target).size : 0
+}
+
+// The old ledger's length the replacement carried.
+function move(ledger: string, moved: Move): number {
+	const archive = archive_of(ledger)
+	const previous = size_of(archive)
+
+	append_text(archive, Buffer.from(moved.archived))
+
+	try {
+		const landed = bytes_past(moved.descriptor, moved.end)
+
+		atomic_write.replace_file(ledger, Buffer.concat([Buffer.from(moved.kept), landed]), {
+			mode: LEDGER_FILE_MODE,
+		})
+
+		return moved.end + landed.length
+	} catch (error) {
+		truncateSync(archive, previous)
+		throw error
+	}
+}
+
+function rotate_open(ledger: string, descriptor: number, cutoff_ms: number): number {
+	const read = bytes_past(descriptor, 0)
+	const end = read.lastIndexOf(LINE_SEPARATOR) + 1
+	const split = partition(read.toString('utf8', 0, end), cutoff_ms)
+
+	if (split.count === 0) return 0
+
+	const carried = move(ledger, { ...split, descriptor, end })
+	const late = bytes_past(descriptor, carried)
+
+	if (late.length > 0) append_text(ledger, late)
+
+	return split.count
+}
+
+function rotate_held(ledger: string, cutoff_ms: number): number {
+	const descriptor = openSync(ledger, READ_FLAGS)
+
+	try {
+		return rotate_open(ledger, descriptor, cutoff_ms)
+	} finally {
+		closeSync(descriptor)
+	}
+}
+
+// The count of records moved: 0 when none is past the retention, the ledger is absent or not this
+// account's, or another rotation holds the lock.
+function rotate(ledger: string, now_ms: number = Date.now()): number {
+	if (!existsSync(ledger) || !stamp_file.is_own_regular_file(ledger)) return 0
+
+	const cutoff_ms = now_ms - RETENTION_DAYS * MS_PER_DAY
+	const lock = `${ledger}${LOCK_SUFFIX}`
+
+	return repository_lock.with_lock_sync(() => rotate_held(ledger, cutoff_ms), lock, NO_WAIT_MS) ?? 0
+}
+
+// This repository's ledger rotated; a test run has no ledger (`lane_ledger.target`).
+async function rotate_target(): Promise<number> {
+	const ledger = await lane_ledger.target()
+
+	return ledger === undefined ? 0 : rotate(ledger)
+}
+
+// The archive's records, then the ledger's — every entry the ledger held before any rotation.
+function history_at(ledger: string): ReadonlyArray<LedgerEntry> {
+	return [...lane_ledger.read_entries(archive_of(ledger)), ...lane_ledger.read_entries(ledger)]
+}
+
+async function read_history(context: ReadContext): Promise<ReadonlyArray<LedgerEntry>> {
+	const ledger = context.ledger_path ?? (await lane_ledger.target())
+
+	return ledger === undefined ? [] : history_at(ledger)
+}
+
+const lane_ledger_archive = { archive_of, history_at, read_history, rotate, rotate_target }
+
+export { lane_ledger_archive }