@joshuafolkken/kit 1.1005.0 → 1.1035.0

package/scripts/lib/read-file.ts

@@ -1,16 +1,40 @@
 import { readFileSync } from 'node:fs'
 
+const ABSENT_CODE = 'ENOENT'
+
+function is_absent(error: unknown): boolean {
+	return error instanceof Error && 'code' in error && error.code === ABSENT_CODE
+}
+
+// An absent file is an answer ("nothing declared here"); any other failure — a permission error, a
+// directory where a file was expected — is not, and is thrown so it cannot pass for an empty file.
+function read_optional(path: string): string | undefined {
+	try {
+		return readFileSync(path, 'utf8')
+	} catch (error) {
+		if (is_absent(error)) return undefined
+
+		throw error
+	}
+}
+
 // Several readers treat an absent file as "nothing declared" rather than an error: a project may
 // carry no lockfile yet, and either overrides location may be missing entirely. Empty content is
 // the shared stand-in, so the callers do not each re-implement the try/catch.
 function read_file_or_empty(path: string): string {
+	return read_optional(path) ?? ''
+}
+
+// For a reader whose contract is to never fail — a hook running after a write already succeeded, a
+// report that states "unreadable" itself — every failure to read, not only absence, is `undefined`.
+function read_if_readable(path: string): string | undefined {
 	try {
 		return readFileSync(path, 'utf8')
 	} catch {
-		return ''
+		return undefined
 	}
 }
 
-const file_reader = { read_file_or_empty }
+const file_reader = { read_optional, read_file_or_empty, read_if_readable }
 
 export { file_reader }

package/scripts/observations/observation-ledger-home.ts

@@ -1,40 +1,105 @@
-import { appendFile, mkdir } from 'node:fs/promises'
+import { appendFile, mkdir, readdir, readFile } from 'node:fs/promises'
 import path from 'node:path'
-import { repo_discovery } from '#scripts/discovery/repo-discovery'
-import { OBSERVATION_LEDGER_PATH } from './observation-ledger'
+import { git_branch } from '#scripts/git/git-branch'
+import { git_spawn } from '#scripts/git/git-spawn'
+import { observation_ledger, OBSERVATION_LEDGER_DIRECTORY } from './observation-ledger'
 import { observation_ledger_migrate } from './observation-ledger-migrate'
 
-// Where the observation ledger is read and written, whichever work tree a command runs in
-// (joshuafolkken/kit#2419).
+// Where the observation ledger is read and written, whichever work tree a command runs in.
 //
-// **The ledger lives in the primary checkout, never in a lane.** A lane is a linked work tree that is
-// closed once its branch merges, and the ledger is excluded from ordinary staging — so a line appended
-// in a lane had no route to the default branch: `pnpm josh followup`'s flush needs `pnpm josh ms`,
-// which a lane refuses, and `lane:close` does not carry the file. Resolving the ledger to the primary
-// checkout at every reader and writer puts the line where the flush already works, rather than adding
-// a second route that moves it there afterwards.
-//
-// The primary checkout is `repo_discovery.main_worktree`'s answer, reused rather than spelled again;
-// in an ordinary checkout it is the given directory itself, so nothing outside a lane changes.
+// **The ledger lives in the work tree the command runs in — a lane's in a lane** (joshuafolkken/kit#2919).
+// It used to resolve to the primary checkout from every lane (joshuafolkken/kit#2419), so a lane's
+// lines waited there for a batch-end flush; another run's stash of that checkout took them, the flush
+// read `git status` and found nothing, and the lines were lost. Each run now appends to its own
+// issue's file in its own tree, `git-staging.ts` commits it with the run, and `pnpm josh followup`
+// commits whatever was appended after that commit before it merges — so a lane's lines reach the
+// default branch with the lane's own pull request, and the primary checkout holds none of them.
 
-function ledger_root(cwd: string = process.cwd()): string {
-	return repo_discovery.main_worktree(cwd)
-}
+const DATE_END = 10
 
-function is_lane(cwd: string = process.cwd()): boolean {
-	return path.resolve(ledger_root(cwd)) !== path.resolve(cwd)
+function ledger_root(cwd: string = process.cwd()): string {
+	return cwd
 }
 
-// **Resolving the path migrates the ledger first** (joshuafolkken/kit#2724). Every reader and writer
-// asks here — `review:record --check`, `review:findings`, the retrospective, the stash carry's
-// duplicate check — so none of them can read an empty new ledger while the lines still sit at the old
-// path, which for the review-record check would answer `not-required` for a round never recorded.
-function ledger_path(cwd: string = process.cwd()): string {
+// **Resolving the directory migrates the single-file ledgers first** (joshuafolkken/kit#2724,
+// joshuafolkken/kit#2919). Every reader and writer asks here — `review:record --check`,
+// `review:findings`, the retrospective, the stash carry's duplicate check — so none of them can read a
+// directory without the lines that still sit at an old path, which for the review-record check would
+// answer `missing` for a round recorded before the move.
+function ledger_directory(cwd: string = process.cwd()): string {
 	const root = ledger_root(cwd)
 
 	observation_ledger_migrate.migrate(root)
 
-	return path.join(root, OBSERVATION_LEDGER_PATH)
+	return path.join(root, OBSERVATION_LEDGER_DIRECTORY)
+}
+
+function file_path(name: number | string, cwd: string): string {
+	ledger_directory(cwd)
+
+	return path.join(ledger_root(cwd), observation_ledger.ledger_file(name))
+}
+
+function issue_path(issue: number, cwd: string = process.cwd()): string {
+	return file_path(issue, cwd)
+}
+
+async function current_branch(cwd: string): Promise<string> {
+	try {
+		return await git_spawn.read(['-C', cwd, 'rev-parse', '--abbrev-ref', 'HEAD'])
+	} catch {
+		return ''
+	}
+}
+
+// **The file a writer that names no issue appends to** — the issue the checked-out branch leads with
+// (`2919-lane`, `2919-store-the-ledger`), so a lane's lines land in its own issue's file; or the date,
+// for a line written on the default branch outside any issue's run, which `pnpm josh
+// observations:flush` commits.
+async function writer_path(now: Date, cwd: string = process.cwd()): Promise<string> {
+	const issue = git_branch.issue_from_branch(await current_branch(cwd))
+
+	return file_path(issue ?? now.toISOString().slice(0, DATE_END), cwd)
+}
+
+// A file whose last line has no newline would otherwise run into the next file's first line.
+async function read_file(target: string): Promise<string> {
+	try {
+		const content = await readFile(target, 'utf8')
+
+		return content.length === 0 || content.endsWith('\n') ? content : `${content}\n`
+	} catch {
+		return ''
+	}
+}
+
+async function ledger_files(directory: string): Promise<ReadonlyArray<string> | undefined> {
+	try {
+		const names = await readdir(directory)
+
+		return names
+			.filter((name) => observation_ledger.is_ledger_file_name(name))
+			.toSorted((left, right) => left.localeCompare(right))
+	} catch {
+		return undefined
+	}
+}
+
+// **Every file in the directory, read as one ledger**, in name order so the answer is stable. Readers
+// count across all of them — a recurrence is a recurrence whichever issue's file each line sits in.
+// `undefined` when there is no directory: a checkout that keeps no ledger, which `review:record
+// --check` turns into `not-required`.
+async function read(cwd: string = process.cwd()): Promise<string | undefined> {
+	const directory = ledger_directory(cwd)
+	const files = await ledger_files(directory)
+
+	if (files === undefined) return undefined
+
+	const contents = await Promise.all(
+		files.map(async (name) => await read_file(path.join(directory, name))),
+	)
+
+	return contents.join('')
 }
 
 // The one append every ledger writer goes through. A consumer that does not keep the ledger has no
@@ -47,6 +112,13 @@ async function append(target: string, lines: ReadonlyArray<string>): Promise<voi
 	await appendFile(target, `${lines.join('\n')}\n`, 'utf8')
 }
 
-const observation_ledger_home = { append, is_lane, ledger_path, ledger_root }
+const observation_ledger_home = {
+	append,
+	issue_path,
+	ledger_directory,
+	ledger_root,
+	read,
+	writer_path,
+}
 
 export { observation_ledger_home }

package/scripts/observations/observation-ledger-migrate.ts

@@ -1,18 +1,20 @@
 import { appendFileSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync } from 'node:fs'
 import path from 'node:path'
+import { file_reader } from '#scripts/lib/read-file'
 import {
-	LEGACY_OBSERVATION_LEDGER_PATH,
+	LEGACY_LEDGER_FILE,
+	LEGACY_OBSERVATION_LEDGER_PATHS,
 	MIGRATION_CLAIM_SUFFIX,
-	OBSERVATION_LEDGER_PATH,
+	OBSERVATION_LEDGER_DIRECTORY,
 } from './observation-ledger'
 import { observation_ledger_line } from './observation-ledger-line'
 
-// Moves the ledger's lines from the path it had before joshuafolkken/kit#2724 to the one it has now
-// (`observation-ledger.ts` carries why both are recognized). Changing the constant alone split the
-// appends across two files: a run still on the old code recreated `docs/observations.md`, and a
-// consumer repository's existing ledger stayed where nothing read it. So resolving the ledger's path
-// migrates first (`observation-ledger-home.ts`), and whatever reached the old path lands at the tail
-// of the new one before anything reads or appends.
+// Moves the ledger's lines from the single files it was before joshuafolkken/kit#2919 into the
+// directory it is now, as `legacy.md` (`observation-ledger.ts` carries why the old paths are still
+// recognized). Changing a constant alone splits the appends: a run still on the old code recreates the
+// old file, and a consumer repository's existing ledger stays where nothing reads it. So resolving the
+// ledger migrates first (`observation-ledger-home.ts`), and whatever reached an old path lands in the
+// directory before anything reads or appends.
 //
 // **The old file is claimed with a rename before it is read.** Two sessions resolving the ledger at
 // once would otherwise both read it and both copy its lines — and a repeated line under one key is
@@ -83,14 +85,6 @@ function terminated(content: string): string {
 	return content.length === 0 || content.endsWith(NEWLINE) ? content : `${content}${NEWLINE}`
 }
 
-function read_or_undefined(file_path: string): string | undefined {
-	try {
-		return readFileSync(file_path, 'utf8')
-	} catch {
-		return undefined
-	}
-}
-
 // What of the claimed file goes to the ledger's tail: all of it, verbatim, when there is no ledger yet,
 // and otherwise only the lines the ledger does not already hold. **The old file can come back after
 // its lines were moved** — `git restore`, `git reset --hard` or a stash without `-u` restores a
@@ -108,7 +102,11 @@ function carried(content: string, ledger: string | undefined): string {
 // Moves one claimed file's lines to the tail of the ledger, then removes the claim.
 function absorb(claimed: string, target: string): void {
 	mkdirSync(path.dirname(target), { recursive: true })
-	appendFileSync(target, carried(readFileSync(claimed, 'utf8'), read_or_undefined(target)), 'utf8')
+	appendFileSync(
+		target,
+		carried(readFileSync(claimed, 'utf8'), file_reader.read_if_readable(target)),
+		'utf8',
+	)
 	rmSync(claimed)
 }
 
@@ -127,10 +125,7 @@ function absorb_stale(legacy: string, target: string): number {
 	return count
 }
 
-// Returns whether anything was moved. `root` is the checkout the ledger lives in.
-function migrate(root: string): boolean {
-	const legacy = path.join(root, LEGACY_OBSERVATION_LEDGER_PATH)
-	const target = path.join(root, OBSERVATION_LEDGER_PATH)
+function migrate_one(legacy: string, target: string): boolean {
 	const recovered = absorb_stale(legacy, target)
 	const claimed = claim_path(legacy)
 
@@ -141,6 +136,16 @@ function migrate(root: string): boolean {
 	return true
 }
 
+// Returns whether anything was moved. `root` is the checkout the ledger lives in. Every old path is
+// tried — `map` before `some`, so one that moved does not leave the next one where it was.
+function migrate(root: string): boolean {
+	const target = path.join(root, OBSERVATION_LEDGER_DIRECTORY, LEGACY_LEDGER_FILE)
+
+	return LEGACY_OBSERVATION_LEDGER_PATHS.map((legacy) =>
+		migrate_one(path.join(root, legacy), target),
+	).some(Boolean)
+}
+
 const observation_ledger_migrate = { claim_path, migrate }
 
 export { observation_ledger_migrate }

package/scripts/observations/observation-ledger-prepare.ts

@@ -1,29 +1,19 @@
-import { readFile } from 'node:fs/promises'
-import path from 'node:path'
-import { OBSERVATION_LEDGER_PATH } from './observation-ledger'
+import { observation_ledger_home } from './observation-ledger-home'
 import { observation_ledger_line, type BrokenLine } from './observation-ledger-line'
-import { observation_ledger_migrate } from './observation-ledger-migrate'
 
-// **What has to hold before a ledger line is committed, asked by both of the paths that commit one**
-// (joshuafolkken/kit#2763): `pnpm josh observations:flush` and the run's own commit in
-// `scripts/git/git-staging.ts`. Lines still on the old path are moved first (joshuafolkken/kit#2724),
-// so the commit carries the move and the lines together, and every entry line is then parsed against
-// the grammar (joshuafolkken/kit#2123) — each caller decides what a broken line costs it.
+// **What has to hold before a ledger line is committed, asked by every path that commits one**
+// (joshuafolkken/kit#2763): `pnpm josh observations:flush`, the run's own commit in
+// `scripts/git/git-staging.ts` and `pnpm josh followup`'s pre-merge ledger commit. Lines still on an
+// old path are moved first (joshuafolkken/kit#2724, joshuafolkken/kit#2919), so the commit carries the
+// move and the lines together, and every entry line is then parsed against the grammar
+// (joshuafolkken/kit#2123) — each caller decides what a broken line costs it.
 //
 // **A ledger that is not there has no line to break** — the change a status saw is then its deletion,
 // and a commit carries that like any other change to it.
-async function read_ledger(root: string): Promise<string> {
-	try {
-		return await readFile(path.join(root, OBSERVATION_LEDGER_PATH), 'utf8')
-	} catch {
-		return ''
-	}
-}
-
 async function prepare(root: string): Promise<ReadonlyArray<BrokenLine>> {
-	observation_ledger_migrate.migrate(root)
-
-	return observation_ledger_line.broken_ledger_lines(await read_ledger(root))
+	return observation_ledger_line.broken_ledger_lines(
+		(await observation_ledger_home.read(root)) ?? '',
+	)
 }
 
 const observation_ledger_prepare = { prepare }

package/scripts/observations/observation-ledger.ts

@@ -1,22 +1,33 @@
-// The observation ledger's one path, named here rather than inside any of the places that act on it
-// (joshuafolkken/kit#1756). `git-staging.ts` stages it with the run's own commit when its grammar
+// The observation ledger's one location, named here rather than inside any of the places that act on
+// it (joshuafolkken/kit#1756). `git-staging.ts` stages it with the run's own commit when its grammar
 // holds (joshuafolkken/kit#2763), `hook-gate-reuse.ts` excludes it from what a hook calls a carried
 // tree, and `observations-flush.ts` commits what no run carried — so a literal in each would be three
 // answers to one question, and a rename reaching only some of them would silently split them.
 //
 // **It sits under `docs/maintainers/`, apart from the reader-facing documents** (joshuafolkken/kit#2724).
-const OBSERVATION_LEDGER_PATH = 'docs/maintainers/observations.md'
-
-// Where the ledger lived before joshuafolkken/kit#2724, kept as a migration source rather than
-// forgotten: a run still on the old code, a stash cut before the move and a consumer repository's
-// existing ledger all write here, and `observation-ledger-migrate.ts` moves what it finds to the path
-// above. Every place that recognizes the ledger recognizes both, so a line on either path is never
-// staged into an ordinary commit. Remove it once every repository holding a ledger has migrated.
-const LEGACY_OBSERVATION_LEDGER_PATH = 'docs/observations.md'
-
-const OBSERVATION_LEDGER_PATHS: ReadonlyArray<string> = [
-	OBSERVATION_LEDGER_PATH,
-	LEGACY_OBSERVATION_LEDGER_PATH,
+//
+// **It is a directory of one file per issue, not one file** (joshuafolkken/kit#2919). One file every
+// run appended to made two lanes' pull requests conflict at its tail, so lanes parked their lines in
+// the primary checkout for a batch-end flush — and another run's stash took them from there, and the
+// flush never saw them. A run now appends to `<issue>.md` in its own work tree and merges it with its
+// own pull request: parallel lanes write different files, so nothing conflicts and nothing waits.
+const OBSERVATION_LEDGER_DIRECTORY = 'docs/maintainers/observations'
+
+const LEDGER_FILE_EXTENSION = '.md'
+
+// What the single-file ledgers held is moved here (`observation-ledger-migrate.ts`), so no line is
+// lost to the split.
+const LEGACY_LEDGER_FILE = `legacy${LEDGER_FILE_EXTENSION}`
+
+// Where the ledger lived as one file — `docs/observations.md` before joshuafolkken/kit#2724 and
+// `docs/maintainers/observations.md` until joshuafolkken/kit#2919 — kept as migration sources rather
+// than forgotten: a run still on the old code, a stash cut before the move and a consumer repository's
+// existing ledger all write there, and `observation-ledger-migrate.ts` moves what it finds into the
+// directory. Every place that recognizes the ledger recognizes them, so a line on either path is never
+// staged into an ordinary commit. Remove them once every repository holding a ledger has migrated.
+const LEGACY_OBSERVATION_LEDGER_PATHS: ReadonlyArray<string> = [
+	'docs/maintainers/observations.md',
+	'docs/observations.md',
 ]
 
 // `git status --porcelain` prints `XY PATH`, so the path starts at the fourth character.
@@ -26,29 +37,48 @@ function status_path(line: string): string {
 	return line.slice(STATUS_PATH_INDEX).trim()
 }
 
-// The suffix of the file a migration renames the old ledger to while it copies it
+// The ledger file one writer appends to — an issue number, or a date for a line written outside any
+// issue's run (`observation-ledger-home.ts` decides which).
+function ledger_file(name: number | string): string {
+	return `${OBSERVATION_LEDGER_DIRECTORY}/${String(name)}${LEDGER_FILE_EXTENSION}`
+}
+
+function is_ledger_file_name(name: string): boolean {
+	return name.endsWith(LEDGER_FILE_EXTENSION)
+}
+
+// The suffix of the file a migration renames an old ledger to while it copies it
 // (`observation-ledger-migrate.ts`): `docs/observations.md.<pid>.migrating`.
 const MIGRATION_CLAIM_SUFFIX = '.migrating'
 
 // A claim left by a process killed mid-migration holds ledger lines, so it is the ledger too: never
 // staged by an ordinary commit, and absorbed by the next migration.
 function is_migration_claim(file_path: string): boolean {
-	return (
-		file_path.startsWith(`${LEGACY_OBSERVATION_LEDGER_PATH}.`) &&
-		file_path.endsWith(MIGRATION_CLAIM_SUFFIX)
+	return LEGACY_OBSERVATION_LEDGER_PATHS.some(
+		(legacy) => file_path.startsWith(`${legacy}.`) && file_path.endsWith(MIGRATION_CLAIM_SUFFIX),
 	)
 }
 
+// Porcelain status collapses an untracked directory to `docs/maintainers/observations/`, so the
+// directory itself, trailing slash and all, is the ledger as much as any file inside it.
+function is_in_directory(file_path: string): boolean {
+	return file_path.startsWith(`${OBSERVATION_LEDGER_DIRECTORY}/`)
+}
+
 function is_ledger_path(file_path: string): boolean {
-	return OBSERVATION_LEDGER_PATHS.includes(file_path) || is_migration_claim(file_path)
+	return (
+		is_in_directory(file_path) ||
+		LEGACY_OBSERVATION_LEDGER_PATHS.includes(file_path) ||
+		is_migration_claim(file_path)
+	)
 }
 
 function is_ledger_line(line: string): boolean {
 	return is_ledger_path(status_path(line))
 }
 
-// The ledger paths a porcelain status names — what a flush stages after a migration, which may be the
-// new file together with the old one's deletion.
+// The ledger paths a porcelain status names — what a commit of the ledger stages, which may be a new
+// file together with an old one's deletion.
 function ledger_paths(status_output: string): ReadonlyArray<string> {
 	return status_output
 		.split('\n')
@@ -57,7 +87,7 @@ function ledger_paths(status_output: string): ReadonlyArray<string> {
 }
 
 // **The one place that answers "does this working tree hold a pending observation append?"**
-// `observations-flush.ts`'s `has_ledger_change` and `pnpm josh followup`'s pre-flush short-circuit
+// `observations-flush.ts`'s `has_ledger_change` and `pnpm josh followup`'s pre-merge ledger commit
 // both ask it (joshuafolkken/kit#1810), so a literal in each would be the clone the header above
 // warns against. A blank porcelain line carries no ledger path, so `is_ledger_line` answers false for
 // it and no filtering is needed.
@@ -67,17 +97,20 @@ function has_pending_append(status_output: string): boolean {
 
 const observation_ledger = {
 	has_pending_append,
+	is_ledger_file_name,
 	is_ledger_line,
 	is_ledger_path,
 	is_migration_claim,
+	ledger_file,
 	ledger_paths,
 	status_path,
 }
 
 export {
-	LEGACY_OBSERVATION_LEDGER_PATH,
+	LEDGER_FILE_EXTENSION,
+	LEGACY_LEDGER_FILE,
+	LEGACY_OBSERVATION_LEDGER_PATHS,
 	MIGRATION_CLAIM_SUFFIX,
-	OBSERVATION_LEDGER_PATH,
-	OBSERVATION_LEDGER_PATHS,
+	OBSERVATION_LEDGER_DIRECTORY,
 	observation_ledger,
 }

package/scripts/observations/observations-flush-cli.ts

@@ -1,38 +1,21 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
-import { observation_ledger_home } from './observation-ledger-home'
+import { error_text } from '#scripts/lib/error-message'
 import { observations_flush } from './observations-flush'
 
 const FAILURE_EXIT_CODE = 1
 
-function message_of(error: unknown): string {
-	return error instanceof Error ? error.message : String(error)
-}
-
-// **From a lane, the flush acts on the primary checkout** (joshuafolkken/kit#2419). That is where the
-// ledger lives (`observation-ledger-home.ts`), and a lane's own checkout is never the one a flush may
-// switch — so the process moves there first, and every refusal after it is about that checkout, which
-// the prefix names so a "run `pnpm josh ms` first" is read as advice for the primary checkout.
-function enter_ledger_home(): string {
-	if (!observation_ledger_home.is_lane()) return ''
-
-	const root = observation_ledger_home.ledger_root()
-
-	process.chdir(root)
-
-	return `The observation ledger lives in the primary checkout, so this flush acts on ${root}: `
-}
-
 // The refusals are the command's whole safety story, so they are printed as the message rather than
 // as a stack: "this checkout is on a feature branch" and "the tree holds somebody else's work" are
 // both things the person fixes in one step, and a trace hides the sentence that says which.
+//
+// **It acts on the checkout it runs in** (joshuafolkken/kit#2919). A lane's ledger lines merge with
+// the lane's own pull request, so a lane has nothing to flush and is refused like any feature branch.
 async function main(): Promise<void> {
-	const prefix = enter_ledger_home()
-
 	try {
-		console.info(`${prefix}${await observations_flush.flush(new Date())}`)
+		console.info(await observations_flush.flush(new Date()))
 	} catch (error) {
-		console.error(`${prefix}${message_of(error)}`)
+		console.error(error_text.message_of(error))
 		process.exit(FAILURE_EXIT_CODE)
 	}
 }

package/scripts/observations/observations-flush-landing.ts

@@ -1,6 +1,7 @@
 import { git_gh_command } from '#scripts/git/git-gh-command'
 import type { OpenPull } from '#scripts/git/git-gh-pr-auto-merge'
 import { git_pr_checks } from '#scripts/git/git-pr-checks'
+import { error_text } from '#scripts/lib/error-message'
 
 // **A flush pull request lands whether or not the flush that opened it is still alive**
 // (joshuafolkken/kit#2497). The merge used to happen only inside the flush's own wait, so a session
@@ -25,7 +26,7 @@ async function request_auto_merge(branch_name: string): Promise<boolean> {
 
 		return true
 	} catch (error) {
-		console.warn(AUTO_MERGE_WARNING, error instanceof Error ? error.message : String(error))
+		console.warn(AUTO_MERGE_WARNING, error_text.message_of(error))
 
 		return false
 	}

package/scripts/observations/observations-flush.ts

@@ -1,15 +1,17 @@
 import { git_command } from '#scripts/git/git-command'
 import { git_gh_command } from '#scripts/git/git-gh-command'
 import { main_sync } from '#scripts/git/main-sync'
-import { observation_ledger, OBSERVATION_LEDGER_PATH } from './observation-ledger'
+import { error_text } from '#scripts/lib/error-message'
+import { observation_ledger, OBSERVATION_LEDGER_DIRECTORY } from './observation-ledger'
 import type { BrokenLine } from './observation-ledger-line'
 import { observation_ledger_prepare } from './observation-ledger-prepare'
 import { observations_flush_landing } from './observations-flush-landing'
 
-// The commit path for the ledger lines no run's own commit carried (joshuafolkken/kit#1756). A run in
-// the primary checkout commits its appended lines with its own pull request (`scripts/git/
-// git-staging.ts`, joshuafolkken/kit#2763), so what is left here is a lane's lines — they sit in the
-// primary checkout, which a lane's commit cannot see — and whatever was appended after a commit.
+// The commit path for the ledger lines no run's own commit carried (joshuafolkken/kit#1756). Every run —
+// a lane's included — commits its appended lines with its own pull request (`scripts/git/
+// git-staging.ts`, joshuafolkken/kit#2763, joshuafolkken/kit#2919), and `pnpm josh followup` commits a
+// line appended after that commit before it merges, so what is left here is a line written on the
+// default branch outside any issue's run — the date-named file `observation-ledger-home.ts` resolves.
 //
 // **The shape is `scripts/release/release-publish.ts`'s, deliberately.** Both open a pull request of
 // their own over one path, wait on the same required checks every other pull request waits on, and
@@ -19,7 +21,7 @@ import { observations_flush_landing } from './observations-flush-landing'
 // below does not survive — `observations-flush-landing.ts` carries why.
 
 const COMMIT_MESSAGE = 'Record observation ledger entries'
-const CLEAN_MESSAGE = `clean — ${OBSERVATION_LEDGER_PATH} matches the commit it sits on, so there is nothing to flush`
+const CLEAN_MESSAGE = `clean — ${OBSERVATION_LEDGER_DIRECTORY} matches the commit it sits on, so there is nothing to flush`
 const BRANCH_PREFIX = 'observations/'
 const SUCCESS_EXIT_CODE = 0
 const RETURN_FAILURE_MESSAGE =
@@ -55,7 +57,7 @@ function branch_name_for(stamp: string): string {
 // single issue, and the ledger's own lines say where each one was seen.
 function pull_request_body(): string {
 	return [
-		`Appended observations from \`${OBSERVATION_LEDGER_PATH}\` that no run's own commit carried.`,
+		`Appended observations from \`${OBSERVATION_LEDGER_DIRECTORY}\` that no run's own commit carried.`,
 		'',
 		'The ledger is append-only, and a second line under one key is what promotes an observation to an issue — so this pull request adds lines and changes none.',
 		'',
@@ -82,10 +84,6 @@ function other_changed_paths(status_output: string): ReadonlyArray<string> {
 	)
 }
 
-function message_of(error: unknown): string {
-	return error instanceof Error ? error.message : String(error)
-}
-
 // **The branch a failed flush leaves behind holds the only copy of those lines**, because the working
 // tree no longer shows them once they are committed. Sending a person to `pnpm josh ms` here — which
 // is what the ordinary off-default refusal says — would abandon them without a word, so this branch
@@ -205,7 +203,9 @@ async function catch_up_default(default_branch: string): Promise<void> {
 	try {
 		await git_command.merge_fast_forward(default_branch)
 	} catch (error) {
-		throw new Error(behind_default_message(default_branch, message_of(error)), { cause: error })
+		throw new Error(behind_default_message(default_branch, error_text.message_of(error)), {
+			cause: error,
+		})
 	}
 }
 
@@ -242,7 +242,9 @@ async function return_to_default_branch(default_branch: string): Promise<void> {
 	try {
 		await git_command.fast_forward_local(default_branch)
 	} catch (error) {
-		throw new Error(`${FAST_FORWARD_FAILURE_MESSAGE} ${message_of(error)}`, { cause: error })
+		throw new Error(`${FAST_FORWARD_FAILURE_MESSAGE} ${error_text.message_of(error)}`, {
+			cause: error,
+		})
 	}
 
 	const exit_code = await main_sync.run([])
@@ -258,7 +260,9 @@ async function push_and_open(branch_name: string): Promise<string> {
 
 		return await git_gh_command.pr_create(COMMIT_MESSAGE, pull_request_body(), 'ignore-for-release')
 	} catch (error) {
-		throw new Error(stranded_branch_message(branch_name, message_of(error)), { cause: error })
+		throw new Error(stranded_branch_message(branch_name, error_text.message_of(error)), {
+			cause: error,
+		})
 	}
 }
 
@@ -279,7 +283,7 @@ async function roll_back(branch_name: string, default_branch: string): Promise<s
 
 		return undefined
 	} catch (error) {
-		return message_of(error)
+		return error_text.message_of(error)
 	}
 }
 
@@ -315,9 +319,12 @@ async function commit_ledger(branch_name: string, default_branch: string): Promi
 	} catch (error) {
 		const roll_back_reason = await roll_back(branch_name, default_branch)
 
-		throw new Error(rejection_message(branch_name, message_of(error), roll_back_reason), {
-			cause: error,
-		})
+		throw new Error(
+			rejection_message(branch_name, error_text.message_of(error), roll_back_reason),
+			{
+				cause: error,
+			},
+		)
 	}
 }
 
@@ -345,7 +352,9 @@ async function land(
 	try {
 		await observations_flush_landing.wait_for_landing(branch_name, is_auto_merge)
 	} catch (error) {
-		throw new Error(stranded_branch_message(branch_name, message_of(error)), { cause: error })
+		throw new Error(stranded_branch_message(branch_name, error_text.message_of(error)), {
+			cause: error,
+		})
 	}
 
 	await return_to_default_branch(default_branch)
@@ -366,7 +375,7 @@ function merged_message(branch_name: string): string {
 function broken_lines_message(broken: ReadonlyArray<BrokenLine>): string {
 	const rows = broken.map((entry) => `  ${entry.line}\n    ↳ ${entry.reason}`).join('\n')
 
-	return `\`${OBSERVATION_LEDGER_PATH}\` has ${String(broken.length)} line(s) that break the ledger grammar, so \`pnpm josh observations:flush\` stops rather than committing them:\n${rows}`
+	return `\`${OBSERVATION_LEDGER_DIRECTORY}\` has ${String(broken.length)} line(s) that break the ledger grammar, so the ledger commit stops rather than carrying them:\n${rows}`
 }
 
 // **A malformed line is refused before a branch is cut, not after.** The ledger path was collected