@joshuafolkken/kit 1.1514.0 → 1.2114.0

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

@@ -0,0 +1,207 @@
+import { lane_implement_subagents, type ImplementLane } from './lane-implement-subagents'
+import { lane_paused_spans, type PausedSpan, type PausedSpans } from './lane-paused-spans'
+import { lane_stage_stats } from './lane-stage-stats'
+import { lane_stats, type StatsWindow } from './lane-stats'
+import type { ToolCall } from './lane-transcript-calls'
+import { lane_transcript_stats } from './lane-transcript-stats'
+
+// The implement stage broken down by what its time went on (joshuafolkken/kit#4887). The ledger's
+// implement is one span per lane, dispatch to the ship's first stage (`lane-stage-stats.ts`); the lane's
+// transcript holds every tool call inside it, so each call's span — from the latest end of the session's
+// 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
+// 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
+// between two sessions of one lane is nobody's. **Nor is the time the lane stood paused**: a
+// `lane:pause` leaves the call in flight on the clock, so its overlap with the lane's paused spans is
+// taken out (joshuafolkken/kit#5168).
+
+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 EDIT_TOOLS: ReadonlySet<string> = new Set(['Edit', 'MultiEdit', 'NotebookEdit', 'Write'])
+const CHECK_COMMANDS: ReadonlySet<string> = new Set([
+	'check:related',
+	'cspell:dot',
+	'gate',
+	'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'])
+// `backgrounded` counts a subagent row's untimed calls (`lane-implement-subagents.ts`); a sub-stage has none.
+const COLUMNS = [
+	'implement sub-stage',
+	'lanes',
+	'median (min)',
+	'max (min)',
+	'backgrounded',
+] as const
+
+interface Phase {
+	edited: boolean
+	reviewing: boolean
+}
+
+// The latest end of the calls seen so far in one session; calls run side by side overlap.
+interface Reach {
+	session_id: ToolCall['session_id'] | undefined
+	end_ms: number
+}
+
+const NO_REACH: Reach = { session_id: undefined, end_ms: 0 }
+
+function runs_any(call: ToolCall, names: ReadonlySet<string>): boolean {
+	return lane_transcript_stats.josh_commands(call.command).some((name) => names.has(name))
+}
+
+function is_edit(call: ToolCall): boolean {
+	return EDIT_TOOLS.has(call.tool ?? '')
+}
+
+// The phase once `call` ran: an edit, or a review started, holds for the rest of the lane.
+function next_phase(call: ToolCall, phase: Phase): Phase {
+	return {
+		edited: phase.edited || is_edit(call),
+		reviewing: phase.reviewing || runs_any(call, REVIEW_COMMANDS),
+	}
+}
+
+function sub_stage_of(call: ToolCall, phase: Phase): SubStage {
+	if (phase.reviewing) return REVIEW_FIX
+	if (is_edit(call)) return EDIT
+	if (runs_any(call, CHECK_COMMANDS)) return CHECK
+
+	return phase.edited ? READ : PLAN
+}
+
+function end_ms(call: ToolCall): number {
+	return call.started_ms + (call.duration_ms ?? 0)
+}
+
+function span_ms(call: ToolCall, reach: Reach): number {
+	if (reach.session_id !== call.session_id) return call.duration_ms ?? 0
+
+	return Math.max(0, end_ms(call) - reach.end_ms)
+}
+
+function next_reach(call: ToolCall, reach: Reach): Reach {
+	const latest = reach.session_id === call.session_id ? reach.end_ms : 0
+
+	return { session_id: call.session_id, end_ms: Math.max(latest, end_ms(call)) }
+}
+
+// The call's span less the time its lane stood paused inside it.
+function active_ms(call: ToolCall, reach: Reach, paused: ReadonlyArray<PausedSpan>): number {
+	const span = span_ms(call, reach)
+	const end = end_ms(call)
+
+	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]))
+	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))
+		reach = next_reach(call, reach)
+	}
+
+	return totals
+}
+
+// One lane's calls before its first ship, or `undefined` when it never shipped.
+function implement_calls(calls: ReadonlyArray<ToolCall>): ReadonlyArray<ToolCall> | undefined {
+	const ship = calls.findIndex((call) => runs_any(call, SHIP_COMMANDS))
+
+	return ship === -1 ? undefined : calls.slice(0, ship)
+}
+
+function lanes_of(calls: ReadonlyArray<ToolCall>): Array<ReadonlyArray<ToolCall>> {
+	const lanes = [...new Set(calls.map((call) => call.lane))]
+
+	return lanes.map((lane) =>
+		calls
+			.filter((call) => call.lane === lane)
+			.toSorted((left, right) => left.started_ms - right.started_ms),
+	)
+}
+
+// One lane's implement calls and paused spans, or `undefined` when it never shipped.
+function implement_lane(
+	lane: ReadonlyArray<ToolCall>,
+	paused: PausedSpans,
+): ImplementLane | undefined {
+	const implement = implement_calls(lane)
+	const spans = lane_paused_spans.of_lane(paused, lane[0]?.lane ?? '')
+
+	return implement === undefined ? undefined : { calls: implement, paused: spans }
+}
+
+// The implement calls and paused spans of each lane that shipped in `window`.
+function implement_lanes(
+	calls: ReadonlyArray<ToolCall>,
+	window: StatsWindow,
+	paused: PausedSpans,
+): Array<ImplementLane> {
+	const lanes = lanes_of(lane_transcript_stats.in_period(calls, window))
+
+	return lanes.flatMap((lane) => implement_lane(lane, paused) ?? [])
+}
+
+// The sub-stage totals of each lane that shipped in `window`.
+function lane_totals_in(
+	calls: ReadonlyArray<ToolCall>,
+	window: StatsWindow,
+	paused: PausedSpans,
+): Array<Totals> {
+	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)
+
+	return [
+		stage,
+		String(values.length),
+		lane_stage_stats.cell(lane_stats.median(values)),
+		lane_stage_stats.cell(lane_stats.peak(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`).
+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)),
+		...lane_implement_subagents.rows(lanes),
+	]
+
+	return [
+		lane_stats.to_row(COLUMNS),
+		lane_stats.to_row(COLUMNS.map(() => '---')),
+		...rows.map((row) => lane_stats.to_row(row)),
+	].join('\n')
+}
+
+const lane_implement_stats = { SUB_STAGES, lane_totals_in, table }
+
+export type { SubStage }
+export { lane_implement_stats }

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

@@ -0,0 +1,90 @@
+import { lane_paused_spans, type PausedSpan } from './lane-paused-spans'
+import { lane_stage_stats } from './lane-stage-stats'
+import { lane_stats } from './lane-stats'
+import type { ToolCall } from './lane-transcript-calls'
+
+// The implement's subagent time by the agent dispatched (joshuafolkken/kit#5297): one row per agent
+// type under `lane:stats`'s implement sub-stages, over the lanes that dispatched it. **A row times the
+// call's own duration**, less the time its lane stood paused inside it — the sub-stages above already
+// put the same call's span to `plan`, `read` or `review-fix`, so the rows break those down rather than
+// add to them. **A backgrounded call is counted, never timed**: its result line is the background
+// notice (`lane-transcript-calls.ts`), so it adds to the row's `backgrounded` count alone — a lane
+// whose calls of a type were all untimed is not among the lanes the median and max are taken over.
+// **The first cell is the type alone**, so a `lane:value cell --row "subagent: <type>"` address holds
+// from one period to the next.
+
+// One lane's implement calls and the spans it stood paused (`lane-implement-stats.ts`).
+interface ImplementLane {
+	calls: ReadonlyArray<ToolCall>
+	paused: ReadonlyArray<PausedSpan>
+}
+
+interface TypeTotal {
+	ms: number
+	timed: number
+	untimed: number
+}
+
+const NO_TOTAL: TypeTotal = { ms: 0, timed: 0, untimed: 0 }
+
+function own_ms(call: ToolCall, paused: ReadonlyArray<PausedSpan>): number {
+	const duration = call.duration_ms ?? 0
+	const end = call.started_ms + duration
+
+	return duration - lane_paused_spans.overlap_ms(paused, call.started_ms, end)
+}
+
+function added(total: TypeTotal, call: ToolCall, paused: ReadonlyArray<PausedSpan>): TypeTotal {
+	return {
+		ms: total.ms + own_ms(call, paused),
+		timed: total.timed + (call.duration_ms === undefined ? 0 : 1),
+		untimed: total.untimed + (call.background ? 1 : 0),
+	}
+}
+
+// Each agent type's summed time and backgrounded count over one lane's implement calls.
+function lane_types(lane: ImplementLane): ReadonlyMap<string, TypeTotal> {
+	const types = new Map<string, TypeTotal>()
+
+	for (const call of lane.calls) {
+		const type = call.subagent?.type
+
+		if (type !== undefined) types.set(type, added(types.get(type) ?? NO_TOTAL, call, lane.paused))
+	}
+
+	return types
+}
+
+// The type's row: its timed lanes, their median and max, and its backgrounded calls over every lane.
+function type_row(type: string, totals: ReadonlyArray<TypeTotal>): Array<string> {
+	const values = totals.filter((total) => total.timed > 0).map((total) => total.ms)
+	const untimed = totals.reduce((sum, total) => sum + total.untimed, 0)
+
+	return [
+		`subagent: ${type}`,
+		String(values.length),
+		lane_stage_stats.cell(lane_stats.median(values)),
+		lane_stage_stats.cell(lane_stats.peak(values)),
+		String(untimed),
+	]
+}
+
+// One row per agent type any lane dispatched, by name; its lanes are the lanes that dispatched it.
+function rows(lanes: ReadonlyArray<ImplementLane>): Array<Array<string>> {
+	const per_lane = lanes.map((lane) => lane_types(lane))
+	const types = [...new Set(per_lane.flatMap((types_of) => [...types_of.keys()]))].toSorted(
+		(left, right) => left.localeCompare(right),
+	)
+
+	return types.map((type) =>
+		type_row(
+			type,
+			per_lane.flatMap((types_of) => types_of.get(type) ?? []),
+		),
+	)
+}
+
+const lane_implement_subagents = { rows }
+
+export type { ImplementLane }
+export { lane_implement_subagents }

package/scripts/lane/lane-install.ts

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs'
-import path from 'node:path'
 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'
 
 // Filling the lane, which is the other half of opening one.
@@ -26,16 +26,9 @@ import { INSTALL_TIMEOUT_MS } from '#scripts/lib/timeouts'
 // exactly the lock committed there. A lock the install would rather rewrite is a finding, not
 // something to absorb silently into six parallel lanes.
 const INSTALL_ARGUMENTS = ['install', '--frozen-lockfile']
-// The manifest whose absence is the whole skip condition. A lane cut from a repository that has no
-// `package.json` has nothing to install, so running `pnpm install` there could only fail on a
-// manifest that was never there — which is exactly the fixture a cross-process lane test needs.
-// The condition is strictly "the file does not exist": a manifest that is
-// present but unreadable or broken still runs the install and still fails as before, so a genuinely
-// broken repository is never passed silently.
-const MANIFEST_FILE_NAME = 'package.json'
 // The lane opens with no dependencies installed, and that is the reported state rather than a
 // failure — there was nothing to install, so nothing failed.
-const NO_MANIFEST_OUTPUT = `No ${MANIFEST_FILE_NAME} in the lane, so the dependency install was skipped.`
+const NO_MANIFEST_OUTPUT = `No ${PACKAGE_JSON} in the lane, so the dependency install was skipped.`
 
 interface InstallResult {
 	is_installed: boolean
@@ -51,7 +44,7 @@ interface InstallResult {
 // `existsSync` answers only whether the path is there, never whether its contents parse, so a
 // present-but-broken manifest falls through to the real install and fails there.
 function has_manifest(directory: string): boolean {
-	return existsSync(path.join(directory, MANIFEST_FILE_NAME))
+	return existsSync(package_manifest.manifest_path(directory))
 }
 
 /**
@@ -87,4 +80,4 @@ async function install_dependencies(directory: string): Promise<InstallResult> {
 const lane_install = { install_dependencies }
 
 export type { InstallResult }
-export { lane_install, INSTALL_ARGUMENTS, MANIFEST_FILE_NAME, NO_MANIFEST_OUTPUT }
+export { lane_install, INSTALL_ARGUMENTS, NO_MANIFEST_OUTPUT }

package/scripts/lane/lane-investigation-switch.ts

@@ -0,0 +1,16 @@
+import { hook_decision } from '#scripts/josh/hook-decision'
+
+// The switch the automatic lane investigations `run:merge` launches — the overrun's
+// (`lane-overrun.ts`) and the baseline's (`lane-baseline.ts`) — share (joshuafolkken/kit#5044). It
+// defaults off, so an unset variable launches no session; `run:merge` loads `.env`, where it is set.
+// Not `JOSH_LANE_OVERRUN`, the mark an investigation session itself carries.
+const INVESTIGATION_ENV_KEY = 'JOSH_LANE_INVESTIGATION'
+
+// Read at call time, so a suite that switches the variable between cases is not answered from a cache.
+function is_on(): boolean {
+	return hook_decision.is_switch_opt_in(INVESTIGATION_ENV_KEY)
+}
+
+const lane_investigation_switch = { is_on }
+
+export { lane_investigation_switch }

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

@@ -1,5 +1,3 @@
-#!/usr/bin/env tsx
-import { fileURLToPath } from 'node:url'
 import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { josh_command } from '#scripts/josh/josh-run'
 import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
@@ -21,7 +19,6 @@ import { execa } from 'execa'
 // warning. Their explanations stream through to stderr; the child's pid is the one thing on stdout.
 // A lane a park kept is the one `already-open` it steps past — `lane_directory` below.
 
-const ARGV_OFFSET = 2
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const should_forward_stderr = true
@@ -171,13 +168,7 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 	return await launch(context)
 }
 
-async function main(argv: ReadonlyArray<string>): Promise<void> {
-	process.exitCode = await run(argv)
-}
-
 const lane_launch_cli = { launch_lane, read_context, run }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
-
 export type { LaunchContext, LaunchOutcome }
 export { lane_launch_cli }

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

@@ -0,0 +1,12 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { lane_launch_cli } from './lane-launch-cli'
+
+// The `josh lane:launch` entry, kept apart from `lane-launch-cli.ts` because other modules import that
+// one: a bundle is one file, so a main guard there would fire for every command that carries it
+// (joshuafolkken/kit#4186).
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const ARGV_OFFSET = 2
+
+	process.exitCode = await lane_launch_cli.run(process.argv.slice(ARGV_OFFSET))
+}

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

@@ -0,0 +1,31 @@
+// The kind each lane ledger line carries — the discriminant `lane-ledger-schema.ts` parses on, kept
+// apart so a schema module of its own can name its kind without importing the union it joins.
+
+const KIND = {
+	MERGE: 'merge',
+	GATE: 'gate',
+	LOAD: 'load',
+	DISPATCH: 'dispatch',
+	STAGE: 'stage',
+	STOP: 'stop',
+	OVERLAP: 'overlap',
+	HELD: 'held',
+	RELEASED: 'released',
+	ROUND_ONE: 'round-one',
+	ROUND_TWO: 'round-two',
+	OFFERABLE: 'offerable',
+	CORE_WAIT: 'core-wait',
+	UNIT_FILES: 'unit-files',
+	TEST_RELATED: 'test-related',
+	TEST_PINNED: 'test-pinned',
+	SPLIT_NOTICE: 'split-notice',
+	SPLIT_FILED: 'split-filed',
+	UNPLANNED_NOTICE: 'unplanned-notice',
+	LANE_STATE: 'lane-state',
+	PUSH_MISS: 'push-miss',
+	SHIP_LAP: 'ship-lap',
+} as const
+
+const lane_ledger_kind = { KIND }
+
+export { lane_ledger_kind }

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

@@ -0,0 +1,49 @@
+import { z } from 'zod'
+import { lane_ledger_kind } from './lane-ledger-kind'
+
+// The lane ledger lines `josh ship` writes about itself — a stop, the preflight's `unplanned` notice
+// and the inner steps of a stage — joined into the entry union by `lane-ledger-schema.ts`.
+
+const { KIND } = lane_ledger_kind
+
+// A `josh ship` that stopped on `issue`: `reason` is the stage it stopped at, or `conflict` — the
+// retrospective's stop reason — and `cause` why (`run-ship-stop-cause.ts`), absent on a stop recorded
+// before it had one. `preconditions` names the kinds a preflight stop found unmet (`run-ship-preflight.ts`),
+// with `pre-detach` where a lane child's fast checks went red (joshuafolkken/kit#4478) and `unpinned`
+// where its `test:pinned` did (joshuafolkken/kit#5228), beside them or alone, absent on any other
+// stop and on one recorded before it had them. `findings` names the `<category>:<severity>` of each
+// finding that decided a review or round-2 stop — the blocking ones, else the fixed ones
+// (joshuafolkken/kit#4426), absent where none decided the stop. How long it stayed stopped is derived
+// from the next ship stage, not recorded, so a resumed ship never has to know the stop it ends.
+const stop_schema = z.object({
+	kind: z.literal(KIND.STOP),
+	at: z.string(),
+	issue: z.number(),
+	reason: z.string(),
+	cause: z.string().optional(),
+	preconditions: z.array(z.string()).optional(),
+	findings: z.array(z.string()).optional(),
+})
+// The ship's `unplanned` answer `josh check:related` printed to the lane of `issue` ahead of the ship,
+// so a preflight `unplanned` stop after it is told apart in `lane:stats` (joshuafolkken/kit#5203).
+const unplanned_notice_schema = z.object({
+	kind: z.literal(KIND.UNPLANNED_NOTICE),
+	at: z.string(),
+	issue: z.number(),
+	files: z.array(z.string()),
+})
+// One inner step of a `josh ship` stage on `issue` — the overlap wait inside `sync`, the scoped pair
+// inside `gate` — so `lane:breakdown` names what a stage spent its time on (joshuafolkken/kit#5294).
+// `at` is its end and `elapsed_ms` its length, as on a stage row.
+const ship_lap_schema = z.object({
+	kind: z.literal(KIND.SHIP_LAP),
+	at: z.string(),
+	issue: z.number(),
+	stage: z.string(),
+	step: z.string(),
+	elapsed_ms: z.number(),
+})
+
+const lane_ledger_schema_ship = { ship_lap_schema, stop_schema, unplanned_notice_schema }
+
+export { lane_ledger_schema_ship }