@joshuafolkken/kit 1.872.0

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

@@ -0,0 +1,97 @@
+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'
+
+// **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
+// cut or a killed process left a green pull request open with nobody to merge it — and once a later
+// flush appended to the same ledger tail, it conflicted and could not land at all. Auto-merge moves
+// the merge to GitHub, and the wait that remains is only for fast-forwarding the local default
+// branch.
+
+const AUTO_MERGE_WARNING =
+	'Could not enable auto-merge on the flush pull request, so it merges only if this command stays alive to merge it:'
+const MERGE_TIMEOUT_REASON =
+	'auto-merge is enabled, but the pull request did not merge within the checks budget'
+const MERGE_FAILED_REASON =
+	'a required check failed or the branch conflicts, so auto-merge will not land the pull request'
+
+// **Best-effort, and the answer says which wait to use.** GraphQL — the only way to enable auto-merge
+// — can be refused in a cloud session (joshuafolkken/kit#1022), and that loses the safety net rather
+// than the flush: the in-process wait-and-merge still runs, exactly as before auto-merge existed.
+async function request_auto_merge(branch_name: string): Promise<boolean> {
+	try {
+		await git_gh_command.pr_enable_auto_merge(branch_name)
+
+		return true
+	} catch (error) {
+		console.warn(AUTO_MERGE_WARNING, error instanceof Error ? error.message : String(error))
+
+		return false
+	}
+}
+
+// With auto-merge on, GitHub merges and this only waits to see it; `pr_merge` is not called, because
+// the merge gate's wait would run out its budget on a pull request that is already merged.
+async function wait_for_landing(branch_name: string, is_auto_merge: boolean): Promise<void> {
+	if (!is_auto_merge) {
+		await git_pr_checks.wait_for_pr_success(branch_name)
+		await git_gh_command.pr_merge(branch_name)
+
+		return
+	}
+
+	const progress = await git_pr_checks.wait_for_pr_merged(branch_name)
+
+	if (progress === 'failed') throw new Error(MERGE_FAILED_REASON)
+	if (progress === 'waiting') throw new Error(MERGE_TIMEOUT_REASON)
+}
+
+function describe_pull(pull: OpenPull): string {
+	return `#${String(pull.number)} (\`${pull.head_ref}\`)`
+}
+
+// **Landing means GitHub will merge it with nobody watching**: auto-merge is on and the merge gate has
+// not failed it — a red check or a conflict leaves auto-merge armed but never firing. One that merged
+// between the listing and this read has landed, so it defers rather than reading as stuck.
+async function is_landing(pull: OpenPull): Promise<boolean> {
+	if (!pull.has_auto_merge) return false
+
+	return (await git_pr_checks.read_merge_progress(pull.head_ref)) !== 'failed'
+}
+
+function landing_flush_message(pulls: ReadonlyArray<OpenPull>): string {
+	return `deferred — an earlier flush pull request is still landing with auto-merge on: ${pulls.map((pull) => describe_pull(pull)).join(', ')}. A new flush branch would conflict with it at the ledger's tail, so the appended observations stay in this working tree for the next flush.`
+}
+
+// **Named rather than silently skipped**, because its lines exist only on its branch: once a later
+// flush appends to the same tail it conflicts and can no longer land by itself. A flush still running
+// in another checkout without auto-merge reads the same way, so the message allows for it.
+function stuck_flush_message(pulls: ReadonlyArray<OpenPull>): string {
+	return `An earlier \`pnpm josh observations:flush\` left a pull request open that nothing will merge — unless a flush in another checkout is still waiting on it: ${pulls.map((pull) => describe_pull(pull)).join(', ')}. Its appended observations exist only on that branch — land it (resolve the ledger conflict if there is one, then merge) before flushing again, or a new flush would conflict with it.`
+}
+
+// **`undefined` means no earlier flush is open, and a flush may cut its branch.** An earlier one that
+// is still landing defers this flush with a message; one that will never land refuses it.
+async function refuse_open_flush(branch_prefix: string): Promise<string | undefined> {
+	const pulls = await git_gh_command.pr_list_open_with_head_prefix(branch_prefix)
+	if (pulls.length === 0) return undefined
+
+	const verdicts = await Promise.all(pulls.map(async (pull) => await is_landing(pull)))
+	const stuck = pulls.filter((_pull, index) => verdicts[index] !== true)
+	if (stuck.length > 0) throw new Error(stuck_flush_message(stuck))
+
+	return landing_flush_message(pulls)
+}
+
+const observations_flush_landing = {
+	landing_flush_message,
+	MERGE_FAILED_REASON,
+	MERGE_TIMEOUT_REASON,
+	refuse_open_flush,
+	request_auto_merge,
+	stuck_flush_message,
+	wait_for_landing,
+}
+
+export { observations_flush_landing }

package/scripts/observations/observations-flush.ts

@@ -0,0 +1,420 @@
+import { readFile } from 'node:fs/promises'
+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 { observation_ledger_line, type BrokenLine } from './observation-ledger-line'
+import { observations_flush_landing } from './observations-flush-landing'
+
+// The commit path the observation ledger did not have (joshuafolkken/kit#1756). The parent session
+// that appends a line never runs `pnpm josh git`; a child runs it inside a lane work tree, which
+// cannot see the parent's checkout at all; and in the primary checkout `git add -u` swept the line
+// into whatever unrelated pull request that run was opening. So the ledger is excluded from ordinary
+// staging (`scripts/git/git-staging.ts`) and this is the one thing that stages it.
+//
+// **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
+// merge — so this reuses the same primitives rather than growing a second answer to "how does a
+// josh command open and land a pull request". The one difference is that this pull request is handed
+// to GitHub's auto-merge as soon as it opens (joshuafolkken/kit#2497), so it lands even when the wait
+// 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 BRANCH_PREFIX = 'observations/'
+const SUCCESS_EXIT_CODE = 0
+const RETURN_FAILURE_MESSAGE =
+	'Could not return this checkout to the default branch; `pnpm josh ms` printed the reason above.'
+const FAST_FORWARD_FAILURE_MESSAGE =
+	'The flush pull request merged, but the local default branch could not be fast-forwarded to it, so this checkout is still on the flush branch:'
+const DATE_END = 10
+const TIME_START = 11
+const TIME_END = 19
+const COLON = ':'
+const NO_COMMITS = 0
+
+// **A count that could not be read is treated as "it may hold a commit".** Of the two refusals below
+// it chooses the one that warns about the only copy, because printing "nothing is stranded" on a
+// branch nobody could measure is the answer that loses lines.
+const UNKNOWN_COMMIT_COUNT = 1
+
+// **Stamped to the second rather than to the minute.** A flush that fails after its commit leaves the
+// branch behind, and a retry inside the same clock unit would die on git's raw `a branch named …
+// already exists` instead of the message below — so the unit is the one a person cannot retry
+// inside.
+function timestamp_for(now: Date): string {
+	const iso = now.toISOString()
+
+	return `${iso.slice(0, DATE_END)}-${iso.slice(TIME_START, TIME_END).replaceAll(COLON, '')}`
+}
+
+function branch_name_for(stamp: string): string {
+	return `${BRANCH_PREFIX}${stamp}`
+}
+
+// **No `closes #N`.** A flush carries whatever observations the last cycle recorded; it answers to no
+// 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}\`, which \`pnpm josh git\` never stages.`,
+		'',
+		'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.',
+		'',
+		'Opened by `pnpm josh observations:flush` (joshuafolkken/kit#1756).',
+	].join('\n')
+}
+
+function status_paths(status_output: string): ReadonlyArray<string> {
+	return status_output
+		.split('\n')
+		.filter((line) => line.trim().length > 0)
+		.map((line) => observation_ledger.status_path(line))
+}
+
+// **Single-sourced with `pnpm josh followup`'s pre-flush short-circuit** (joshuafolkken/kit#1810):
+// the ledger-change test lives in `observation-ledger.ts`, so the two callers cannot drift.
+function has_ledger_change(status_output: string): boolean {
+	return observation_ledger.has_pending_append(status_output)
+}
+
+function other_changed_paths(status_output: string): ReadonlyArray<string> {
+	return status_paths(status_output).filter((file_path) => file_path !== OBSERVATION_LEDGER_PATH)
+}
+
+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
+// of the refusal says the opposite.
+//
+// **The exits it names are ones the caller can actually take** (joshuafolkken/kit#1785). It used to
+// say "finish or delete that branch", and both are closed to an agent: the distributed
+// `.claude/settings.json` denies `Bash(git commit*)` and `Bash(git branch -d*)`, and `pnpm josh git`
+// excludes the ledger from staging by design (joshuafolkken/kit#1756), so finishing through it is not
+// possible either. Pushing the branch and landing its pull request is the route that is open.
+function stranded_flush_message(current: string): string {
+	return `\`${current}\` is a flush branch an earlier \`pnpm josh observations:flush\` left behind, and its appended observations are committed only there. Land it before flushing again — \`git push -u origin ${current}\`, then open and merge its pull request; \`pnpm josh ms\` here would leave the only copy of those lines behind.`
+}
+
+// **A flush branch with no commit on it strands nothing, so it is told the opposite**
+// (joshuafolkken/kit#1785). The appended lines never left the working tree, which makes the "only
+// copy" premise above factually false here — and makes `pnpm josh ms` the correct exit, the very one
+// the other message forbids.
+function empty_flush_message(current: string): string {
+	return `\`${current}\` is a flush branch an earlier \`pnpm josh observations:flush\` left behind with no commit on it, so nothing is stranded: the appended observations are still in this working tree. Run \`pnpm josh ms\` and flush again — that cuts a fresh branch and loses no line, leaving \`${current}\` as an empty branch to clear whenever it suits you.`
+}
+
+function flush_branch_message(current: string, commit_count: number): string {
+	return commit_count === NO_COMMITS
+		? empty_flush_message(current)
+		: stranded_flush_message(current)
+}
+
+// **Two refusals rather than one taking a count it may not use.** Only the flush-branch arm reads a
+// commit count, so the ordinary off-default refusal is a function of its own and
+// `refuse_off_default` below spawns `git rev-list` for the arm that needs it alone.
+function off_default_message(current: string, default_branch: string): string {
+	return `\`pnpm josh observations:flush\` opens a branch of its own, so it starts from \`${default_branch}\` — this checkout is on \`${current}\`. Run \`pnpm josh ms\` first.`
+}
+
+// **A branch cut from a default branch that predates another merged flush conflicts by
+// construction** (joshuafolkken/kit#1768). The ledger is append-only and every writer adds at the
+// same tail, so a stale start point opens a pull request `wait_for_pr_success` waits on until it
+// exhausts its budget rather than merging. The flush fast-forwards first (joshuafolkken/kit#2462), so
+// this is printed only when that fast-forward was refused — the reason is git's own.
+function behind_default_message(default_branch: string, reason: string): string {
+	return `\`pnpm josh observations:flush\` cuts its branch from \`${default_branch}\`, which is behind \`origin/${default_branch}\` and could not be fast-forwarded (${reason}) — a branch cut here would open a pull request that cannot merge. Run \`pnpm josh ms\` first.`
+}
+
+function is_flush_branch(current: string): boolean {
+	return current.startsWith(BRANCH_PREFIX)
+}
+
+// **The rollback has already run, so this says what is now true rather than what to go and do.** The
+// checkout is back on the default branch, the branch is gone, and the appended lines are where they
+// always were — so the next attempt is this same command, once whatever rejected the commit is fixed.
+function rejected_commit_message(branch_name: string, reason: string): string {
+	return `The ledger's commit was rejected, so \`${branch_name}\` was removed and this checkout is back on the default branch: ${reason} — the appended observations are still in the working tree. Fix what was rejected and run \`pnpm josh observations:flush\` again.`
+}
+
+// **The rollback did not finish, so nothing here claims the branch is gone.** The message above
+// would assert a removal that did not happen, which is worse than saying nothing: it is what sends
+// somebody looking for a branch that is still sitting in the checkout. Both reasons are carried in
+// the one error the command exits with rather than one of them being printed above it.
+//
+// **"Nothing was committed to it" is traceable rather than measured** — the commit that would have
+// put something there is the one that was just rejected — so the exit is `empty_flush_message`'s,
+// which is also the refusal the next run will print.
+function roll_back_failure_message(
+	branch_name: string,
+	reason: string,
+	roll_back_reason: string,
+): string {
+	return `The ledger's commit was rejected and \`${branch_name}\` could not be cleaned up afterwards. The commit was rejected by: ${reason}. The cleanup failed with: ${roll_back_reason}. Nothing was committed to that branch and the appended observations are still in the working tree, so \`pnpm josh ms\` followed by another flush loses no line.`
+}
+
+// **A tree holding anything else is somebody's work in progress**, and a flush that carried it would
+// be the contamination this command exists to end, pointing the other way.
+function other_changes_message(paths: ReadonlyArray<string>): string {
+	return `The working tree holds changes besides the ledger, so \`pnpm josh observations:flush\` stops rather than committing them: ${paths.join(', ')}`
+}
+
+// One message for every failure after the commit, because they all leave the same thing behind: the
+// appended lines committed on the flush branch and nowhere the working tree can show them. The
+// checkout is deliberately left on that branch, so the refusal above fires on the next attempt.
+function stranded_branch_message(branch_name: string, reason: string): string {
+	return `The ledger is committed on \`${branch_name}\` and the flush then failed: ${reason} — those lines now exist only on that branch, and this checkout is still on it. Finish that branch's pull request before running \`pnpm josh ms\` here.`
+}
+
+async function commits_beyond(base: string, tip: string): Promise<number> {
+	try {
+		return await git_command.commit_count_beyond(base, tip)
+	} catch {
+		return UNKNOWN_COMMIT_COUNT
+	}
+}
+
+async function refuse_off_default(current: string, default_branch: string): Promise<never> {
+	if (!is_flush_branch(current)) throw new Error(off_default_message(current, default_branch))
+
+	throw new Error(flush_branch_message(current, await commits_beyond(default_branch, current)))
+}
+
+// **The start point's freshness is judged without moving the working tree**, which is the whole
+// point of doing it here rather than pulling (joshuafolkken/kit#1768). `git fetch` updates the
+// remote-tracking ref and `git rev-list --count HEAD..origin/<default>` reads it — neither writes a
+// file, so the ledger, dirty by definition when this runs, is left exactly as it is.
+async function commits_behind_default(default_branch: string): Promise<number> {
+	await git_command.fetch_branch(default_branch)
+
+	return await git_command.commit_count_beyond('HEAD', `origin/${default_branch}`)
+}
+
+// **A default branch that is only behind is brought forward rather than refused**
+// (joshuafolkken/kit#2462). A lane's flush acts on the primary checkout, whose default branch is
+// behind by the lane's own merge every time — so the refusal alone stopped every lane close. A
+// `--ff-only` merge moves no file the dirty ledger conflicts with: git refuses it, untouched, when an
+// incoming commit changes the ledger too, and only that case is still refused.
+async function catch_up_default(default_branch: string): Promise<void> {
+	if ((await commits_behind_default(default_branch)) === NO_COMMITS) return
+
+	try {
+		await git_command.merge_fast_forward(default_branch)
+	} catch (error) {
+		throw new Error(behind_default_message(default_branch, message_of(error)), { cause: error })
+	}
+}
+
+// Returns the default branch, which is what the rollback below checks out again.
+async function refuse_unsafe_flush(status_output: string): Promise<string> {
+	const current = await git_command.branch()
+	const default_branch = await git_command.get_default_branch()
+
+	if (current !== default_branch) await refuse_off_default(current, default_branch)
+
+	const others = other_changed_paths(status_output)
+
+	if (others.length > 0) throw new Error(other_changes_message(others))
+
+	return default_branch
+}
+
+// **`main_sync.run` rather than a third copy of its three lines.** `pnpm josh ms` and
+// `pnpm josh release`'s own `finally` already spell out "read the default branch, check it out, pull
+// it", and writing it again here would be the clone `CLAUDE.md` prohibits. Reusing the command also
+// brings its refusal inside a linked work tree, which is a precondition this flush wants anyway.
+//
+// **Its exit code is read rather than discarded**: `run` catches its own errors and returns `1`, so a
+// checkout left on the flush branch would otherwise be reported as a completed flush.
+//
+// **The local default branch is fast-forwarded before it is checked out** (joshuafolkken/kit#2462).
+// Lines appended while the pull request waited leave the ledger dirty, and git refuses to check out a
+// default branch whose ledger differs from the flush branch's. Once the merge is in, the fast-forwarded
+// default branch holds the same ledger the flush branch does, so the checkout carries those lines over.
+//
+// **A failed fast-forward says the merge is already in**, so the person reading it knows the ledger
+// lines are safe and only this checkout is left on the flush branch.
+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 })
+	}
+
+	const exit_code = await main_sync.run([])
+
+	if (exit_code !== SUCCESS_EXIT_CODE) throw new Error(RETURN_FAILURE_MESSAGE)
+}
+
+// Everything after the commit, so a failure here can say what is on the branch and what it costs to
+// walk away from it.
+async function push_and_open(branch_name: string): Promise<string> {
+	try {
+		await git_command.push()
+
+		return await git_gh_command.pr_create(COMMIT_MESSAGE, pull_request_body())
+	} catch (error) {
+		throw new Error(stranded_branch_message(branch_name, message_of(error)), { cause: error })
+	}
+}
+
+// **The side that created the branch is the side that rolls it back** (joshuafolkken/kit#1785). A
+// commit rejected by the pre-commit hook used to leave the branch behind with nothing on it, and the
+// refusal the next run printed named two exits an agent cannot take. Nothing is stranded at this
+// point — the appended lines are still in the working tree, staged and uncommitted — so returning to
+// the default branch and removing the branch loses none of them.
+//
+// **Its own failure is returned rather than thrown or printed**, so the single error the command
+// exits with can carry both facts — why the commit was rejected, and whether the branch is still
+// there. Printed above the throw it scrolled past the message that mattered; thrown over it, the
+// reason for the rejection was lost outright. `undefined` means the rollback finished.
+async function roll_back(branch_name: string, default_branch: string): Promise<string | undefined> {
+	try {
+		await git_command.checkout(default_branch)
+		await git_command.delete_branch(branch_name)
+
+		return undefined
+	} catch (error) {
+		return message_of(error)
+	}
+}
+
+// **The message is chosen from what the rollback did, never assumed.** A rollback that could not
+// check the default branch out leaves the branch exactly where it was, and a message asserting its
+// removal would send somebody looking for something that is still in the checkout.
+function rejection_message(
+	branch_name: string,
+	reason: string,
+	roll_back_reason: string | undefined,
+): string {
+	if (roll_back_reason === undefined) return rejected_commit_message(branch_name, reason)
+
+	return roll_back_failure_message(branch_name, reason, roll_back_reason)
+}
+
+async function commit_ledger(branch_name: string, default_branch: string): Promise<void> {
+	try {
+		await git_command.add_path(OBSERVATION_LEDGER_PATH)
+		await git_command.commit(COMMIT_MESSAGE)
+	} 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,
+		})
+	}
+}
+
+async function open_pull_request(branch_name: string, default_branch: string): Promise<string> {
+	await git_command.checkout_b(branch_name)
+	await commit_ledger(branch_name, default_branch)
+
+	return await push_and_open(branch_name)
+}
+
+// **The checkout goes back to the default branch only on the way that merged.** A `finally` here
+// would check the default branch out after a red check too — and `docs/observations.md` would then
+// revert to main's content, leaving the appended lines on a branch nothing in this checkout points
+// at any more. The next flush would read `has_ledger_change` as false and report `clean`, which is
+// the silent loss the refusals above exist to prevent. Left on the branch, the refusal fires.
+//
+// With auto-merge on, a failed wait no longer strands the lines for good — GitHub still merges once
+// the checks pass (joshuafolkken/kit#2497) — but the checkout stays on the branch all the same,
+// because only a merge this command has seen makes returning to the default branch safe.
+async function land(
+	branch_name: string,
+	default_branch: string,
+	is_auto_merge: boolean,
+): Promise<void> {
+	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 })
+	}
+
+	await return_to_default_branch(default_branch)
+}
+
+async function open_and_land(branch_name: string, default_branch: string): Promise<void> {
+	console.info(await open_pull_request(branch_name, default_branch))
+
+	const is_auto_merge = await observations_flush_landing.request_auto_merge(branch_name)
+
+	await land(branch_name, default_branch, is_auto_merge)
+}
+
+function merged_message(branch_name: string): string {
+	return `merged \`${branch_name}\` — the appended observations are on the default branch`
+}
+
+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}`
+}
+
+// **A malformed line is refused before a branch is cut, not after.** The ledger path was collected
+// without a line ever being parsed (joshuafolkken/kit#2123), so a broken append could ride a flush
+// through; validating here keeps the committed ledger to its grammar.
+async function refuse_broken_ledger(): Promise<void> {
+	const broken = observation_ledger_line.broken_ledger_lines(
+		await readFile(OBSERVATION_LEDGER_PATH, 'utf8'),
+	)
+
+	if (broken.length > 0) throw new Error(broken_lines_message(broken))
+}
+
+// **Nothing pulls in front of the branch, and that is deliberate.** The ledger is dirty by
+// definition at this point, so `git pull --ff-only` aborts on it in exactly the case a pull would
+// have been for — an upstream flush that already advanced the ledger — and reports a failure about
+// the wrong thing (joshuafolkken/kit#1756's second review round). So the freshness of the start
+// point is read from the remote first (joshuafolkken/kit#1768), and `catch_up_default` fast-forwards
+// only where git can do it without touching the ledger (joshuafolkken/kit#2462): a default branch
+// that predates another merged flush still stops here — before a branch is cut — rather than opening
+// a pull request that cannot merge. An earlier flush pull request still open is checked for the same
+// reason (joshuafolkken/kit#2497): a branch cut beside it conflicts with it at the ledger's tail.
+async function flush(now: Date): Promise<string> {
+	const status_output = await git_command.status()
+	const default_branch = await refuse_unsafe_flush(status_output)
+
+	if (!has_ledger_change(status_output)) return CLEAN_MESSAGE
+
+	await refuse_broken_ledger()
+
+	const deferred = await observations_flush_landing.refuse_open_flush(BRANCH_PREFIX)
+	if (deferred !== undefined) return deferred
+
+	await catch_up_default(default_branch)
+
+	const branch_name = branch_name_for(timestamp_for(now))
+
+	await open_and_land(branch_name, default_branch)
+
+	return merged_message(branch_name)
+}
+
+const observations_flush = {
+	behind_default_message,
+	branch_name_for,
+	broken_lines_message,
+	CLEAN_MESSAGE,
+	COMMIT_MESSAGE,
+	empty_flush_message,
+	flush,
+	flush_branch_message,
+	has_ledger_change,
+	merged_message,
+	off_default_message,
+	other_changed_paths,
+	other_changes_message,
+	pull_request_body,
+	rejected_commit_message,
+	roll_back_failure_message,
+	stranded_branch_message,
+	timestamp_for,
+}
+
+export { observations_flush }

package/scripts/overrides/lockfile-overrides.ts

@@ -0,0 +1,105 @@
+import { yaml_document } from '#scripts/yaml/yaml-document'
+import { overrides_check } from './overrides-logic'
+import { lockfile_importers_schema, type LockfileImporter } from './schemas'
+
+// The importer sections whose entries pnpm rewrites through `overrides` before resolving.
+const DEPENDENCY_GROUPS = ['dependencies', 'devDependencies', 'optionalDependencies'] as const
+
+// Specifier protocols that name a source rather than a registry range. An override cannot rewrite
+// one into a comparable range, so comparing it against an override value could only ever produce a
+// false mismatch.
+const NON_REGISTRY_PREFIXES = ['link:', 'file:', 'workspace:', 'catalog:', 'npm:', '$']
+
+interface SpecifierMismatch {
+	importer: string
+	name: string
+	lockfile_specifier: string
+	override: string
+}
+
+function is_non_registry(value: string): boolean {
+	return NON_REGISTRY_PREFIXES.some((prefix) => value.startsWith(prefix))
+}
+
+// A key carrying a version selector (`pkg@>=5`) applies only to the dependents whose declared range
+// matches the selector, which cannot be decided from the lockfile alone. Only a bare key rewrites
+// every occurrence of the package, so only a bare key yields a specifier the importer must equal.
+function is_comparable_entry(key: string, value: string): boolean {
+	return overrides_check.extract_package_name(key) === key && !is_non_registry(value)
+}
+
+function read_unconditional_overrides(overrides: Record<string, string>): Map<string, string> {
+	const comparable = Object.entries(overrides).filter(([key, value]) =>
+		is_comparable_entry(key, value),
+	)
+
+	return new Map(comparable)
+}
+
+function find_entry_mismatch(
+	importer: string,
+	name: string,
+	specifier: string,
+	override: string | undefined,
+): Array<SpecifierMismatch> {
+	if (override === undefined) return []
+	if (is_non_registry(specifier)) return []
+	if (specifier === override) return []
+
+	return [{ importer, name, lockfile_specifier: specifier, override }]
+}
+
+function find_importer_mismatches(
+	importer: string,
+	sections: LockfileImporter,
+	overrides: Map<string, string>,
+): Array<SpecifierMismatch> {
+	return DEPENDENCY_GROUPS.flatMap((group) =>
+		Object.entries(sections[group] ?? {}).flatMap(([name, entry]) =>
+			find_entry_mismatch(importer, name, entry.specifier, overrides.get(name)),
+		),
+	)
+}
+
+function read_document_importers(
+	document: Record<string, unknown>,
+): Array<[string, LockfileImporter]> {
+	return Object.entries(lockfile_importers_schema.parse(document).importers ?? {})
+}
+
+function read_importers(lockfile_content: string): Array<[string, LockfileImporter]> {
+	return yaml_document
+		.parse_yaml_documents(lockfile_content)
+		.flatMap((document) => read_document_importers(document))
+}
+
+// Compares what the lockfile records against what the overrides declare. pnpm writes the
+// override-applied specifier into each importer entry, so a difference means the lockfile no longer
+// matches the manifest pnpm derives — the state that fails `pnpm install --frozen-lockfile` in CI
+// while `trustLockfile: true` keeps the same command quiet locally (kit #744).
+function find_specifier_mismatches(
+	lockfile_content: string,
+	overrides: Record<string, string>,
+): Array<SpecifierMismatch> {
+	const unconditional = read_unconditional_overrides(overrides)
+	if (unconditional.size === 0) return []
+
+	return read_importers(lockfile_content).flatMap(([importer, sections]) =>
+		find_importer_mismatches(importer, sections, unconditional),
+	)
+}
+
+function format_mismatch_line(mismatch: SpecifierMismatch): string {
+	const recorded = `lockfile ${mismatch.lockfile_specifier}, override ${mismatch.override}`
+
+	return `  ${mismatch.name} (importer ${mismatch.importer}): ${recorded}`
+}
+
+function format_mismatch_lines(mismatches: ReadonlyArray<SpecifierMismatch>): Array<string> {
+	return mismatches.map((mismatch) => format_mismatch_line(mismatch))
+}
+
+const lockfile_overrides = { find_specifier_mismatches, format_mismatch_lines }
+
+export type { SpecifierMismatch }
+export { lockfile_overrides }