@joshuafolkken/kit 1.1005.0 → 1.1035.0

package/scripts/josh/josh-script-reader.ts

@@ -1,11 +0,0 @@
-import { readFileSync } from 'node:fs'
-import path from 'node:path'
-import { fileURLToPath } from 'node:url'
-
-const REPOSITORY_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..')
-
-function read_script(script: string): string {
-	return readFileSync(path.join(REPOSITORY_ROOT, script), 'utf8')
-}
-
-export { read_script }

package/scripts/package/production-dependency-graph.ts

@@ -1,68 +0,0 @@
-interface LockDependency {
-	specifier: string
-	version: string
-}
-
-interface LockSnapshot {
-	dependencies?: Record<string, string>
-	optionalDependencies?: Record<string, string>
-}
-
-interface LockImporter {
-	dependencies: Record<string, LockDependency>
-	optionalDependencies?: Record<string, LockDependency>
-}
-
-interface Lockfile {
-	importers: Record<string, LockImporter>
-	snapshots: Record<string, LockSnapshot>
-}
-
-function collect_snapshot(
-	lockfile: Lockfile,
-	names: Set<string>,
-	name: string,
-	version: string,
-): void {
-	const key = `${name}@${version}`
-	if (names.has(key)) return
-	const snapshot = lockfile.snapshots[key]
-	if (!snapshot) throw new Error(`Missing production snapshot: ${key}`)
-	names.add(key)
-
-	const children = { ...snapshot.dependencies, ...snapshot.optionalDependencies }
-
-	for (const [child, child_version] of Object.entries(children)) {
-		collect_snapshot(lockfile, names, child, child_version)
-	}
-}
-
-function root_version(importer: LockImporter, name: string, specifier: string): string {
-	const entry = importer.dependencies[name] ?? importer.optionalDependencies?.[name]
-	if (entry?.specifier !== specifier) throw new Error(`Production lockfile mismatch: ${name}`)
-
-	return entry.version
-}
-
-function production_names(
-	lockfile: Lockfile,
-	dependencies: Record<string, string>,
-	optional_dependencies: Record<string, string> = {},
-): Set<string> {
-	const seen = new Set<string>()
-	const importer = lockfile.importers['.']
-	if (!importer) throw new Error('Missing root importer in production lockfile')
-
-	const roots = { ...dependencies, ...optional_dependencies }
-
-	for (const [name, specifier] of Object.entries(roots)) {
-		collect_snapshot(lockfile, seen, name, root_version(importer, name, specifier))
-	}
-
-	return new Set([...seen].map((key) => key.slice(0, key.lastIndexOf('@'))))
-}
-
-const production_dependency_graph = { names: production_names }
-
-export type { Lockfile }
-export { production_dependency_graph }

package/scripts/retrospective/retrospective-cli.ts

@@ -1,97 +0,0 @@
-#!/usr/bin/env tsx
-import { readFile } from 'node:fs/promises'
-import { fileURLToPath } from 'node:url'
-import { cost_run_report, type RunCostReport } from '#scripts/cost/cost-run-report'
-import { cost_run_tree } from '#scripts/cost/cost-run-tree'
-import { observation_ledger_home } from '#scripts/observations/observation-ledger-home'
-import { observation_ledger_line } from '#scripts/observations/observation-ledger-line'
-import { review_finding_ledger } from '#scripts/review/review-finding-ledger'
-import { run_carry } from '#scripts/run/run-carry'
-import { run_event_scope, type EventScope } from '#scripts/run/run-event-scope'
-import { run_event_stream, type RunEvent } from '#scripts/run/run-event-stream'
-import { retrospective, type RetrospectiveInputs } from './retrospective'
-
-// `josh retrospective` — the end-of-run retrospective (joshuafolkken/kit#2328). It is the aggregation
-// half: it gathers the four measurements that already exist and prints the digest `retrospective.ts`
-// composes, so the retrospective step has one place to read the run it just finished. **When to run it
-// is the run driver's** — `run:step` prints it at the stop position, once per invocation — and **what to
-// file from it is `retrospective.md`'s**; this only reads and shapes.
-//
-// **Kit-only.** It reads kit's own development run — its transcript store, its review ledger, its event
-// stream — so it means nothing in a consumer project and is dropped from a consumer's help and refused
-// there, through the existing `is_kit_only` declaration rather than a new judgement.
-
-const SUCCESS_EXIT_CODE = 0
-// `read_from` returns every event past the given position, so zero is "the whole stream from the start".
-const STREAM_START = 0
-
-function read_cost(cwd: string): RunCostReport | undefined {
-	const tree = cost_run_tree.load(cwd, undefined)
-
-	if (tree === undefined) return undefined
-
-	return cost_run_report.build(tree.run_count, tree.unattributed_count, tree.nodes)
-}
-
-async function read_ledger(): Promise<string> {
-	try {
-		return await readFile(observation_ledger_home.ledger_path(), 'utf8')
-	} catch {
-		return ''
-	}
-}
-
-function ledger_entries(content: string): Array<string> {
-	return content.split('\n').filter((line) => observation_ledger_line.is_ledger_entry_line(line))
-}
-
-interface RunRead {
-	events: ReadonlyArray<RunEvent>
-	scope: EventScope
-}
-
-// The stream and the scope that bounds it, read from the one directory the carry record and the event stream
-// share (joshuafolkken/kit#2395). The whole stream is read — `scoped_events` filters it to this invocation —
-// and an unresolvable directory has no record to scope with, which is the undetermined answer an absent
-// record gives.
-async function read_run(): Promise<RunRead> {
-	const directory = await run_carry.repository_directory()
-
-	if (directory === undefined) return { events: [], scope: run_event_scope.UNKNOWN_EVENT_SCOPE }
-
-	const target = run_event_stream.target_of(directory)
-	const { events } = run_event_stream.read_from(target, STREAM_START)
-	const scope = run_event_scope.scope_of(run_carry.read_carry(run_carry.carry_path(directory)))
-
-	return { events, scope }
-}
-
-async function gather(cwd: string): Promise<RetrospectiveInputs> {
-	const ledger = await read_ledger()
-	const run_read = await read_run()
-
-	return {
-		cost: read_cost(cwd),
-		findings: review_finding_ledger.category_counts(ledger),
-		zero_rounds: review_finding_ledger.zero_round_count(ledger),
-		observations: ledger_entries(ledger),
-		events: run_read.events,
-		scope: run_read.scope,
-	}
-}
-
-async function run(cwd: string = process.cwd()): Promise<number> {
-	console.info(retrospective.compose(await gather(cwd)))
-
-	return SUCCESS_EXIT_CODE
-}
-
-async function main(): Promise<void> {
-	process.exitCode = await run()
-}
-
-const retrospective_cli = { gather, run, main }
-
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main()
-
-export { retrospective_cli }

package/scripts/retrospective/retrospective.ts

@@ -1,127 +0,0 @@
-import { cost_format } from '#scripts/cost-runtime/cost-format'
-import type { RunCostReport } from '#scripts/cost/cost-run-report'
-import type { RoleTotals } from '#scripts/cost/cost-run-roles'
-import type { CategoryCount } from '#scripts/review/review-finding-ledger'
-import { run_event_scope, type EventScope } from '#scripts/run/run-event-scope'
-import type { RunEvent } from '#scripts/run/run-event-stream'
-
-// The composition half of `josh retrospective` — the end-of-run retrospective's aggregation
-// (joshuafolkken/kit#2328). A run that drains its backlog has spent time and money that nobody reads;
-// this folds the four measurements that already exist — the run tree's cost and time
-// (`cost-run-report.ts`), the recurring review findings (`review-finding-ledger.ts`), the observation
-// ledger and the run's own event stream — into one digest, so the retrospective step has something to
-// weigh. It adds no new measurement, per the observation-filing rule against readerless numbers; every
-// input here is read from a command that was already keeping it.
-//
-// **It is a pure function of the four inputs.** The gathering — loading the run tree, reading the
-// ledger, opening the stream — is the CLI's; this shapes what they return and nothing else, so the
-// digest is unit-tested against fixed inputs rather than against a live store.
-
-const MS_PER_MINUTE = 60_000
-const PERCENT = 100
-// A role whose share of the run's wall clock runs this far ahead of its share of the cost is time the
-// run spent waiting rather than working — the disparity the retrospective exists to surface (the wake
-// role in the baseline sat at 52% of the time for 25% of the cost, a gap of 0.27).
-const WAITING_GAP = 0.2
-
-// The friction each event kind marks — a place the run did not run straight through — counted back
-// over the whole run. A plan, a child launch, a merge and a PR opening are the run working as intended,
-// so they are not friction and are left out.
-const FRICTION_KINDS = ['park', 'outage', 'cut', 'review-round'] as const
-
-interface RetrospectiveInputs {
-	cost: RunCostReport | undefined
-	findings: ReadonlyArray<CategoryCount>
-	zero_rounds: number
-	// The observation ledger's entry lines, already filtered to entries by the caller.
-	observations: ReadonlyArray<string>
-	events: ReadonlyArray<RunEvent>
-	// Which invocation the friction count covers (joshuafolkken/kit#2395). The stream is the repository's
-	// event log, not this run's, so a digest handed the whole of it would report a previous invocation's
-	// cut and park as this run's friction — the very numbers the retrospective weighs to file improvement
-	// issues. The scope is `run-event-scope.ts`'s, shared with `run:report` and `run:step`.
-	scope: EventScope
-}
-
-const CLOSING =
-	'Weigh these against retrospective.md: file the improvements worth carrying into the next run, and stack the rest in the observation ledger.'
-
-function minutes(ms: number): string {
-	return String(Math.round(ms / MS_PER_MINUTE))
-}
-
-function percent(share: number): string {
-	return `${String(Math.round(share * PERCENT))}%`
-}
-
-// A role's time share running ahead of its cost share is the run waiting rather than working, so it is
-// called out; a role that pays its way carries no note.
-function waiting_note(role: RoleTotals): string {
-	return role.elapsed_share - role.cost_share >= WAITING_GAP ? ' — waiting-heavy' : ''
-}
-
-function role_line(role: RoleTotals): string {
-	const spent = `${percent(role.cost_share)} cost, ${percent(role.elapsed_share)} time`
-
-	return `  ${role.role}: ${spent}${waiting_note(role)}`
-}
-
-function cost_lines(cost: RunCostReport | undefined): Array<string> {
-	if (cost === undefined) return ['Run cost & time: no run transcripts found']
-
-	const totals = `${String(cost.session_count)} session(s), ${minutes(cost.total_elapsed_ms)} min, ${cost_format.format_usd(cost.total_usd)}`
-
-	return [`Run cost & time: ${totals}`, ...cost.roles.map((role) => role_line(role))]
-}
-
-function findings_lines(
-	findings: ReadonlyArray<CategoryCount>,
-	zero_rounds: number,
-): Array<string> {
-	const denominator = `${String(zero_rounds)} zero-finding round(s)`
-
-	if (findings.length === 0) return [`Review findings: none recorded (${denominator})`]
-
-	const body = findings.map((entry) => `  ${entry.category}: ${String(entry.count)}`)
-
-	return [`Review findings (${denominator}):`, ...body]
-}
-
-function observation_lines(observations: ReadonlyArray<string>): Array<string> {
-	return [`Observation ledger: ${String(observations.length)} entry(ies) held`]
-}
-
-function friction_count(events: ReadonlyArray<RunEvent>, kind: string): number {
-	return events.filter((event) => event.kind === kind).length
-}
-
-// This invocation's friction, counted over its own events only. An undetermined scope falls to an empty
-// list rather than the whole stream (joshuafolkken/kit#2395): counting every invocation's friction as this
-// run's is the defect, so the safe fall is to attribute nothing that cannot be attributed.
-function friction_lines(events: ReadonlyArray<RunEvent>, scope: EventScope): Array<string> {
-	const scoped = run_event_scope.scoped_events(events, scope) ?? []
-	const counts = FRICTION_KINDS.map((kind) => `${kind} ${String(friction_count(scoped, kind))}`)
-
-	return [`Run events: ${counts.join(', ')}`]
-}
-
-// The four sections in a fixed order, separated by blank lines, closed by the pointer that hands the
-// judgement — which improvements are worth filing — to `retrospective.md`.
-function compose(inputs: RetrospectiveInputs): string {
-	return [
-		...cost_lines(inputs.cost),
-		'',
-		...findings_lines(inputs.findings, inputs.zero_rounds),
-		'',
-		...observation_lines(inputs.observations),
-		'',
-		...friction_lines(inputs.events, inputs.scope),
-		'',
-		CLOSING,
-	].join('\n')
-}
-
-const retrospective = { CLOSING, FRICTION_KINDS, WAITING_GAP, compose }
-
-export type { RetrospectiveInputs }
-export { retrospective }

package/scripts/rules/delivered-rules-harness.ts

@@ -1,72 +0,0 @@
-import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import path from 'node:path'
-import { delivered_rules } from './delivered-rules'
-
-// The payload machinery two delivery suites share (joshuafolkken/kit#2119). `delivered-rules.test.ts`
-// had it first; the filing rules — the scout gate and the per-run cap — need the same temp transcript,
-// payload envelope and per-rule stamp cleanup, so a second copy in `delivered-rules-filing.test.ts`
-// would be the clone `CLAUDE.md` prohibits. Each suite calls `create_harness()` once, so each gets its
-// own work directory and its own tracked transcripts.
-
-const PRE_TOOL_USE = 'PreToolUse'
-const BASH_TOOL = 'Bash'
-
-interface Harness {
-	// The temp directory this harness's transcripts live under.
-	work: string
-	// Every transcript file written, so a suite can clean the batching stamp keyed on each of them.
-	written: ReadonlySet<string>
-	transcript_for: (name: string, text?: string) => string
-	payload_for: (transcript: string, command: string, tool_name?: string) => string
-	payload_of: (name: string, command: string, tool_name?: string, history?: string) => string
-	// Removes every rule's once-per-run stamp for every written transcript, then the work directory.
-	cleanup: () => void
-}
-
-function payload_for(transcript: string, command: string, tool_name = BASH_TOOL): string {
-	return JSON.stringify({
-		hook_event_name: PRE_TOOL_USE,
-		transcript_path: transcript,
-		tool_name,
-		tool_input: { command },
-	})
-}
-
-function create_harness(prefix = 'rule-guard-'): Harness {
-	const work = mkdtempSync(path.join(tmpdir(), prefix))
-	const written = new Set<string>()
-
-	// The trigger reads the call, never the history, so an empty transcript is the honest fixture — it
-	// proves the decision came from the command rather than from anything behind it.
-	function transcript_for(name: string, text = ''): string {
-		const target = path.join(work, `${name}.jsonl`)
-
-		writeFileSync(target, text)
-		written.add(target)
-
-		return target
-	}
-
-	// `history` is the transcript behind the call, empty for a case that reads only the command.
-	function payload_of(name: string, command: string, tool_name = BASH_TOOL, history = ''): string {
-		return payload_for(transcript_for(name, history), command, tool_name)
-	}
-
-	function cleanup(): void {
-		for (const transcript of written) {
-			for (const rule of delivered_rules.DELIVERED_RULES) {
-				rmSync(delivered_rules.delivery_path(rule.id, transcript), { force: true })
-			}
-		}
-
-		rmSync(work, { recursive: true, force: true })
-	}
-
-	return { work, written, transcript_for, payload_for, payload_of, cleanup }
-}
-
-const delivered_rules_harness = { create_harness }
-
-export type { Harness }
-export { delivered_rules_harness }

package/scripts/rules/top-level-scripts-guard.ts

@@ -1,47 +0,0 @@
-import { readdirSync } from 'node:fs'
-import path from 'node:path'
-import { fileURLToPath } from 'node:url'
-
-// `scripts/` is grouped into domain subdirectories (joshuafolkken/kit#2013). A file placed directly
-// under `scripts/` is what this guard forbids: flat files are hard to find, coarsen the changed-file
-// scope, and inflate an agent's investigation reads. The scripts root is one level above this rule's
-// own directory.
-const SCRIPTS_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..')
-
-// The extensions a top-level file would carry — every executable script is one of these. A stray
-// `.md` or `.json` at the root is not what the layout is about, so it is not guarded.
-const GUARDED_EXTENSIONS: ReadonlyArray<string> = ['.ts', '.sh']
-
-// Files permitted directly under `scripts/`. Empty today — every script lives in a domain
-// subdirectory — so a new top-level file is a mistake until someone adds it here with a reason.
-const TOP_LEVEL_ALLOWLIST: ReadonlySet<string> = new Set<string>()
-
-function is_guarded_file(name: string): boolean {
-	return GUARDED_EXTENSIONS.some((extension) => name.endsWith(extension))
-}
-
-// The guarded top-level names that are not allowlisted. Kept pure over a plain listing so its own
-// unit test can exercise it without touching the filesystem.
-function top_level_offenders(
-	entries: ReadonlyArray<string>,
-	allowlist: ReadonlySet<string> = TOP_LEVEL_ALLOWLIST,
-): Array<string> {
-	return entries.filter((name) => is_guarded_file(name) && !allowlist.has(name))
-}
-
-// The real names sitting directly under `scripts/`, files only — subdirectories are the whole point
-// of the layout, so they are never offenders.
-function read_top_level_entries(): Array<string> {
-	return readdirSync(SCRIPTS_ROOT, { withFileTypes: true })
-		.filter((entry) => entry.isFile())
-		.map((entry) => entry.name)
-}
-
-const top_level_scripts_guard = {
-	SCRIPTS_ROOT,
-	TOP_LEVEL_ALLOWLIST,
-	top_level_offenders,
-	read_top_level_entries,
-}
-
-export { top_level_scripts_guard }

package/scripts/run/run-carry-flush.ts

@@ -1,58 +0,0 @@
-import { PORCELAIN_FLAG, UNTRACKED_FILES_FLAG } from '#scripts/git/constants'
-import { git_spawn } from '#scripts/git/git-spawn'
-import { josh_command } from '#scripts/josh/josh-run'
-import { observation_ledger } from '#scripts/observations/observation-ledger'
-import { observation_ledger_home } from '#scripts/observations/observation-ledger-home'
-
-// The one observation-ledger flush a `backlogrun` makes, at its end (joshuafolkken/kit#2492).
-//
-// A lane child used to flush after every merge (`run:tail`'s first step): a ledger-only branch, pull
-// request and full CI run per issue, minutes each, for a file only the retrospective and the
-// measurements read. The lanes now leave their lines appended in the primary checkout — the ledger's
-// only home (`observation-ledger-home.ts`) — and `run:carry --end` commits them all in one pull request
-// once the record is gone. `--end` is the batch's one end across every session cut, and the second
-// `--end` finds no record and flushes nothing, so the flush is once per invocation.
-//
-// **It runs after the retrospective, not before**, and loses nothing by it: the retrospective reads the
-// ledger file on disk (`retrospective-cli.ts` → `read_ledger`), not main, and the lines it stacks
-// itself land in the same pull request. **A line a cut or a crash left unflushed is not lost either**:
-// it is still a pending append in the primary checkout, and the next flush — this one, a later run's,
-// or a single run's `followup` — sees it from `git status`, whichever run wrote it.
-//
-// **A failed flush is reported, never allowed to keep the record standing.** The lines stay on disk for
-// the next flush, while a record that outlived its run would make the next `--begin` read `busy` — so
-// `--end` clears the record before it flushes. A flush killed before its commit leaves only the lines
-// in the working tree; one killed after it leaves them on its pull request's branch, which GitHub's
-// auto-merge lands once the checks pass (joshuafolkken/kit#2497).
-
-const FLUSH_ARGV: ReadonlyArray<string> = ['observations:flush']
-const SUCCESS_EXIT_CODE = 0
-const FAILURE_NOTE =
-	'The observation ledger flush failed; its lines stay in the primary checkout for the next flush (`pnpm josh observations:flush`).'
-
-async function has_pending_append(): Promise<boolean> {
-	const root = observation_ledger_home.ledger_root()
-	const status = await git_spawn.read(['-C', root, 'status', PORCELAIN_FLAG, UNTRACKED_FILES_FLAG])
-
-	return observation_ledger.has_pending_append(status)
-}
-
-// Standard output is `run:carry`'s one-token contract, so every word of the flush goes to standard
-// error — the flush's own explanation is forwarded there, and its report is copied after it.
-async function flush_ledger(): Promise<void> {
-	try {
-		if (!(await has_pending_append())) return
-
-		const result = await josh_command.josh_run(FLUSH_ARGV, true)
-
-		if (result.out.length > 0) console.error(result.out)
-
-		if (result.code !== SUCCESS_EXIT_CODE) console.error(FAILURE_NOTE)
-	} catch {
-		console.error(FAILURE_NOTE)
-	}
-}
-
-const run_carry_flush = { FAILURE_NOTE, FLUSH_ARGV, flush_ledger }
-
-export { run_carry_flush }

package/scripts/run/run-transcript.golden.txt

@@ -1,57 +0,0 @@
-## child-completion
-a launched child runs through to its merge
-  start              verdict  implement
-  planned            verdict  implement
-  child launched     verdict  wait
-  child merged       command  pnpm josh run:merge 2250
-
-## park
-a child is parked and the batch moves on
-  start              verdict  implement
-  child parked       command  pnpm josh backlog:next
-
-## cut-and-resume
-the run is cut before its gate, then resumes to the merge
-  start              verdict  implement
-  cut taken          command  pnpm josh run:cut --resume 2250
-  resumed, pr open   command  pnpm josh followup
-  second review      command  pnpm josh review:round2
-  merged             command  pnpm josh run:merge 2250
-
-## lanes-full
-every lane holds a child, so the parent waits
-  start              verdict  implement
-  lanes full         verdict  wait
-
-## consecutive-failure-stop
-the failure guard stops the run
-  start              verdict  implement
-  outage             command  pnpm josh run:merge 2250
-  guard stops        command  pnpm josh retrospective
-
-## drain-retrospective
-the backlog drains, so the retrospective runs before the idle watch
-  start              verdict  implement
-  backlog drained    command  pnpm josh retrospective
-  retrospective done verdict  wait
-
-## expired-budget
-the whole-run budget is spent — a person decides
-  start              decide   decide: whole-run budget spent — resume with `pnpm josh run:carry --resume` | discard with `pnpm josh run:carry --end`
-
-## unreadable-carry
-the carry record cannot be read
-  start              verdict  unknown
-
-## closed-already-done
-the issue is already closed, whatever the events say
-  start              verdict  already-done
-  after a merge      verdict  already-done
-
-## needs-human-review
-the issue stops before its commit for a person
-  start              verdict  human-review
-
-## update-deps-first
-a required dependency update comes before implementing
-  start              verdict  update-deps

package/scripts/run/run-wake-work.ts

@@ -1,108 +0,0 @@
-import { backlog_stalled } from '#scripts/backlog/backlog-stalled'
-import { josh_command } from '#scripts/josh/josh-run'
-import { lane_capacity } from '#scripts/lane/lane-capacity'
-import { lane_registry } from '#scripts/lane/lane-registry'
-import { run_carry, type CarryRead } from './run-carry'
-import { run_invocation } from './run-invocation'
-
-// Whether a session the supervisor is about to wake would find anything to do (joshuafolkken/kit#2417).
-//
-// **This is what stops the whiff at its source.** The wake decision read the carry record alone, so a
-// session was launched whether or not there was work, and a woken session that found the backlog empty
-// or every lane taken ended without touching anything — a full agent session, preamble and all, bought
-// to learn one boolean. Asked here, in the supervisor's own process, the same boolean costs a
-// `git worktree list` and at most one `backlog:next`, and no session at all.
-//
-// **Cheap first, as the stall detector reads it.** The named issues left on the carry record need no
-// I/O; the free-lane count is local; `backlog:next` is the one network read, and it is made only where
-// a lane is free for its answer to go into. Both counts are read with the stall detector's primitives
-// (`lane_capacity`, `lane_registry`, `count_ready_tokens`), so "a free lane and a ready issue" means one
-// thing in both places.
-//
-// **`undefined` is "cannot tell", and the caller wakes on it.** A failed read is not an empty pool: read
-// as one, an outage would defer every launch until the idle ceiling, stalling a run that had work. That
-// is why neither of the stall detector's readers is reused whole — it reads an unreadable lane limit
-// and a failed `backlog:next` as zero, the safe direction for a stall report and the wrong one here —
-// and why a read that throws (a `git worktree list` caught mid-prune) is caught rather than ending the
-// supervisor.
-
-const NO_FREE = 0
-const NO_READY = 0
-const SUCCESS_EXIT_CODE = 0
-const TRIAGE_WORK = 1
-
-interface WorkPorts {
-	// The free-lane count, or `undefined` where the lane limit could not be read.
-	free_lane_count: () => Promise<number | undefined>
-	// The runnable count, or `undefined` where `backlog:next` could not answer.
-	ready_count: () => Promise<number | undefined>
-}
-
-async function real_ready_count(): Promise<number | undefined> {
-	const result = await josh_command.josh_run(['backlog:next'], true)
-
-	if (result.code !== SUCCESS_EXIT_CODE) return undefined
-	// A `triage` answer offers no number, but the untriaged issues are a session's to judge
-	// (joshuafolkken/kit#2779) — counted as one piece of work, or the whole pool would idle with nobody judging it.
-	if (backlog_stalled.needs_triage(result.out)) return TRIAGE_WORK
-
-	return backlog_stalled.count_ready_tokens(result.out)
-}
-
-async function real_free_lane_count(): Promise<number | undefined> {
-	const limit = lane_capacity.lane_limit()
-
-	if (limit.kind !== 'limit') return undefined
-
-	const lanes = await lane_registry.list_lanes()
-	const live = lanes.filter((lane) => !lane.is_stranded).length
-
-	return lane_capacity.free_lanes(limit.limit, live)
-}
-
-const DEFAULT_WORK_PORTS: WorkPorts = {
-	free_lane_count: real_free_lane_count,
-	ready_count: real_ready_count,
-}
-
-// **Work the record answers without a read.** Named issues still to run are work by definition, and a
-// `--only` run whose named list is done is work of a different kind: the session is needed to finish
-// the run, and there is no pool it could be waiting on — deferring it would only delay the report.
-function is_owed_by_record(read: CarryRead): boolean {
-	if (read.kind !== 'carried') return true
-
-	const remaining = run_carry.remaining_of(read.carry)
-
-	if (remaining !== undefined && remaining.length > NO_READY) return true
-
-	return run_invocation.has_only(read.carry.invocation)
-}
-
-async function read_pool(ports: WorkPorts): Promise<boolean | undefined> {
-	const free = await ports.free_lane_count()
-
-	if (free === undefined) return undefined
-	if (free <= NO_FREE) return false
-
-	const ready = await ports.ready_count()
-
-	return ready === undefined ? undefined : ready > NO_READY
-}
-
-async function has_work(
-	read: CarryRead,
-	ports: WorkPorts = DEFAULT_WORK_PORTS,
-): Promise<boolean | undefined> {
-	if (is_owed_by_record(read)) return true
-
-	try {
-		return await read_pool(ports)
-	} catch {
-		return undefined
-	}
-}
-
-const run_wake_work = { DEFAULT_WORK_PORTS, has_work }
-
-export type { WorkPorts }
-export { run_wake_work }