@joshuafolkken/kit 1.3000.0 → 1.3041.0

package/scripts/observations/observations-flush.ts

@@ -1,13 +1,16 @@
 import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { git_pr_checks } from '#scripts/gh/git-pr-checks'
 import { git_command } from '#scripts/git/git-command'
 import { main_sync } from '#scripts/git/main-sync'
 import { IGNORE_FOR_RELEASE_LABEL } from '#scripts/issue/issue-labels'
 import { error_text } from '#scripts/lib/error-message'
 import { review_comment_carry } from '#scripts/review/review-comment-carry'
 import { observation_ledger, OBSERVATION_LEDGER_DIRECTORY } from './observation-ledger'
+import { observation_ledger_archive } from './observation-ledger-archive'
 import type { BrokenLine } from './observation-ledger-line'
 import { observation_ledger_prepare } from './observation-ledger-prepare'
 import { observations_flush_landing } from './observations-flush-landing'
+import { observations_flush_transaction } from './observations-flush-transaction'
 
 // The commit path for the ledger lines no run's own commit carried. Every run —
 // a lane's included — commits its appended lines with its own pull request (`scripts/git/
@@ -29,13 +32,12 @@ 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
+const NO_ARCHIVED_FILES = 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
@@ -58,11 +60,22 @@ function branch_name_for(stamp: string): string {
 
 // **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 {
+//
+// **A flush that archived says it moved lines** (joshuafolkken/kit#7336): "changes none" would be
+// false of the removed files, so it says what holds instead — every line moved, none dropped.
+function ledger_change_sentence(archived_files: number): string {
+	if (archived_files === NO_ARCHIVED_FILES) {
+		return 'so this pull request adds lines and changes none.'
+	}
+
+	return `so this pull request drops none: it adds lines, and moves ${String(archived_files)} closed issues' file(s) verbatim into the monthly \`archive-YYYY-MM.md\` files.`
+}
+
+function pull_request_body(archived_files: number): string {
 	return [
 		`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.',
+		`The ledger is append-only, and a second line under one key is what promotes an observation to an issue — ${ledger_change_sentence(archived_files)}`,
 		'',
 		'Opened by `pnpm josh observations:flush` (joshuafolkken/kit#1756).',
 	].join('\n')
@@ -212,7 +225,7 @@ async function catch_up_default(default_branch: string): Promise<void> {
 	}
 }
 
-// Returns the default branch, which is what the rollback below checks out again.
+// Refuse another person's work before creating the isolated flush checkout.
 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()
@@ -226,155 +239,28 @@ async function refuse_unsafe_flush(status_output: string): Promise<string> {
 	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**.
-// 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.
+// The source stayed on the default branch; main:sync owns its fast-forward and exit status.
 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} ${error_text.message_of(error)}`, {
-			cause: error,
-		})
-	}
-
+	if ((await git_command.branch()) !== default_branch) throw new Error(RETURN_FAILURE_MESSAGE)
 	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> {
+// Publication failures retain the isolated commit and the source records for retry.
+async function push_and_open(branch_name: string, body: string): Promise<string> {
 	try {
 		await git_command.push()
 
-		return await git_gh_command.pr_create(
-			COMMIT_MESSAGE,
-			pull_request_body(),
-			IGNORE_FOR_RELEASE_LABEL,
-		)
-	} catch (error) {
-		throw new Error(stranded_branch_message(branch_name, error_text.message_of(error)), {
-			cause: error,
-		})
-	}
-}
-
-// **The side that created the branch is the side that rolls it back**, so a commit rejected by the
-// pre-commit hook does not leave the branch behind with nothing on it. 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 error_text.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)
-}
-
-// **Every ledger path the status names is staged, not the one constant**.
-// After a migration the change is the new file together with the old one's deletion, and a commit
-// holding only the first would leave the deletion behind as a change no later flush could tell apart
-// from a fresh append.
-async function stage_ledger(): Promise<void> {
-	const ledger_paths = observation_ledger.ledger_paths(await git_command.status())
-
-	for (const file_path of ledger_paths) {
-		// eslint-disable-next-line no-await-in-loop -- git add holds the index lock, so two at once fail
-		await git_command.add_path(file_path)
-	}
-}
-
-async function commit_ledger(branch_name: string, default_branch: string): Promise<void> {
-	try {
-		await stage_ledger()
-		await git_command.commit(COMMIT_MESSAGE)
+		return await git_gh_command.pr_create(COMMIT_MESSAGE, body, IGNORE_FOR_RELEASE_LABEL)
 	} catch (error) {
-		const roll_back_reason = await roll_back(branch_name, default_branch)
-
 		throw new Error(
-			rejection_message(branch_name, error_text.message_of(error), roll_back_reason),
-			{
-				cause: error,
-			},
+			`The ledger is committed on \`${branch_name}\` in the recovery worktree; publication failed: ${error_text.message_of(error)}. The source checkout and original records are preserved. Rerun \`pnpm josh observations:flush\` from the source checkout to resume.`,
+			{ 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 the ledger 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 does not strand the lines for good — GitHub still merges once
-// the checks pass — 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, error_text.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`
 }
@@ -385,64 +271,78 @@ function broken_lines_message(broken: ReadonlyArray<BrokenLine>): string {
 	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
-// without a line ever being parsed, so a broken append could ride a flush
-// through; validating here keeps the committed ledger to its grammar. The migration and the parse are
-// `observation-ledger-prepare.ts`'s, shared with the run's own commit.
+// Validate the isolated payload before staging it.
 async function prepare_ledger(): Promise<void> {
 	const broken = await observation_ledger_prepare.prepare(process.cwd())
 
 	if (broken.length > 0) throw new Error(broken_lines_message(broken))
 }
 
-// The checkout made safe and caught up: a carried file an earlier flush left uncommitted is discarded
-// first, since it would make git refuse the fast-forward (`review-comment-carry.ts`).
+// Recovery must precede a freshness check: an already landed archive can conflict with the snapshot.
 async function ready_default_branch(status_output: string): Promise<string> {
 	const default_branch = await refuse_unsafe_flush(status_output)
 
-	review_comment_carry.discard_uncommitted(status_output, process.cwd())
-	await catch_up_default(default_branch)
+	if (status_output.split('\n').some((line) => /^[^ ?]/u.test(line))) {
+		throw new Error(
+			'Staged changes must be committed or unstaged before observations:flush; index left untouched',
+		)
+	}
+
+	if (!(await observations_flush_transaction.pending(process.cwd()))) {
+		await catch_up_default(default_branch)
+	}
 
 	return default_branch
 }
 
-// **The closed issues' comment rounds are carried only once a flush will go ahead**
-// (joshuafolkken/kit#5326): a lane child leaves them to this flush, so the carried files ride its pull
-// request, and the status is read again so a carry alone is a change to flush. A carry left behind by
-// a later stop is discarded by the next flush's `ready_default_branch`.
-async function carried_status(): Promise<string> {
+// Partial archival must throw: the transaction rebuilds it from its durable snapshot on retry.
+async function carried_status(): Promise<{ status_output: string; archived_files: number }> {
 	await review_comment_carry.carry_reported(process.cwd())
 
-	return await git_command.status()
+	const archived_files = await observation_ledger_archive.archive(process.cwd())
+
+	return { status_output: await git_command.status(), archived_files }
 }
 
-// **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. So the freshness of the start
-// point is read from the remote first, and `catch_up_default` fast-forwards
-// only where git can do it without touching the ledger: 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: a branch cut beside it conflicts with it at the ledger's tail. So the order is: ready the
-// default branch, defer to an open flush, carry, then check, prepare and land.
-async function flush(now: Date): Promise<string> {
-	const default_branch = await ready_default_branch(await git_command.status())
+// Carry, migration and archival run only in the isolated checkout.
+async function prepare_isolated(): Promise<number> {
+	const { archived_files } = await carried_status()
 
-	const deferred = await observations_flush_landing.refuse_open_flush(BRANCH_PREFIX)
-	if (deferred !== undefined) return deferred
+	await prepare_ledger()
+
+	return archived_files
+}
 
-	const status_output = await carried_status()
+async function publish_isolated(branch_name: string, archived_files: number): Promise<void> {
+	if ((await git_pr_checks.read_merge_progress(branch_name)) === 'merged') return
+	const open = await git_gh_command.pr_list_open_with_head_prefix(branch_name)
 
-	if (!has_ledger_change(status_output)) return CLEAN_MESSAGE
+	if (open.length === 0) {
+		console.info(await push_and_open(branch_name, pull_request_body(archived_files)))
+	}
 
-	await prepare_ledger()
+	const is_auto_merge = await observations_flush_landing.request_auto_merge(branch_name)
+
+	await observations_flush_landing.wait_for_landing(branch_name, is_auto_merge)
+}
 
+async function flush(now: Date): Promise<string> {
+	const default_branch = await ready_default_branch(await git_command.status())
+	const is_pending = await observations_flush_transaction.pending(process.cwd())
+	const deferred = is_pending
+		? undefined
+		: await observations_flush_landing.refuse_open_flush(BRANCH_PREFIX)
+	if (deferred !== undefined) return deferred
 	const branch_name = branch_name_for(timestamp_for(now))
 
-	await open_and_land(branch_name, default_branch)
+	const committed_branch = await observations_flush_transaction.run(process.cwd(), branch_name, {
+		prepare: prepare_isolated,
+		publish: publish_isolated,
+	})
+	if (committed_branch === '') return CLEAN_MESSAGE
+	await return_to_default_branch(default_branch)
 
-	return merged_message(branch_name)
+	return merged_message(committed_branch)
 }
 
 const observations_flush = {

package/scripts/plan/plan-scaffold-cli.ts

@@ -8,6 +8,7 @@ import { project_checks } from '#scripts/gate/project-checks'
 import { plan_consumers } from '#scripts/issue/plan-consumers'
 import { josh_environment_file } from '#scripts/josh/josh-environment-file'
 import { session_language } from '#scripts/josh/session-language'
+import { lane_plan_estimate } from '#scripts/lane/lane-plan-estimate'
 import { line_budget } from '#scripts/lines/line-budget'
 import { run_prep_cli } from '#scripts/run/run-prep-cli'
 import { run_prep_locate } from '#scripts/run/run-prep-locate'
@@ -22,7 +23,7 @@ import { plan_scaffold, type ScaffoldParts, type Targets } from './plan-scaffold
 const ARGV_OFFSET = 2
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
-const USAGE = 'Usage: josh plan:scaffold <issue-number> [<path>...]'
+const USAGE = 'Usage: josh plan:scaffold <issue-number> [<path>...] [--estimate <json-file>]'
 
 // A backticked directory is not a planned file: only a regular file reaches `lines` and `test:declared`.
 function is_file(target: string): boolean {
@@ -79,7 +80,11 @@ async function gather(
 	return { summary, files, near_limit: rows, declared, cases: owed, consumers }
 }
 
-async function scaffold(issue_number: string, paths: ReadonlyArray<string>): Promise<number> {
+async function scaffold(
+	issue_number: string,
+	paths: ReadonlyArray<string>,
+	estimate?: string,
+): Promise<number> {
 	const summary = await run_prep_cli.read_summary(issue_number)
 
 	if (summary === undefined) {
@@ -92,16 +97,22 @@ async function scaffold(issue_number: string, paths: ReadonlyArray<string>): Pro
 		run_prep_locate.extract_targets(summary.body),
 		is_file,
 	)
-	const files = paths.length > 0 ? paths : targets.files
+	const planned = estimate !== undefined || paths.length > 0 ? paths : targets.files
+	const scope = await lane_plan_estimate.attach(
+		{ issue: Number(issue_number), paths: [...planned], planned_at: '' },
+		estimate,
+	)
+	const parts = await gather(summary.text, scope.paths, targets)
 
-	console.info(plan_scaffold.format(await gather(summary.text, files, targets)))
+	console.info(plan_scaffold.format({ ...parts, estimate: scope.estimated_size }))
 
 	return SUCCESS_EXIT_CODE
 }
 
 // A malformed number is an argument error (usage); an unreadable body is a read failure (its own note).
 async function run(argv: ReadonlyArray<string>): Promise<number> {
-	const [first = '', ...paths] = argv
+	const input = lane_plan_estimate.split(argv)
+	const [first = '', ...paths] = input.tokens
 	const issue_number = run_prep_cli.parse_number([first])
 
 	if (issue_number === undefined) {
@@ -110,7 +121,7 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 		return FAILURE_EXIT_CODE
 	}
 
-	return await scaffold(issue_number, paths)
+	return await scaffold(issue_number, paths, input.file)
 }
 
 async function main(argv: ReadonlyArray<string>): Promise<void> {

package/scripts/plan/plan-scaffold.ts

@@ -1,5 +1,7 @@
 import path from 'node:path'
+import { issue_body_keys } from '#scripts/issue/issue-body-keys'
 import { line_budget, type FileBudget } from '#scripts/lines/line-budget'
+import type { DeclaredSize } from '#scripts/split/split-assess'
 import { test_declared_logic, type Verdict } from '#scripts/test/test-declared-logic'
 
 // The formatting half of `josh plan:scaffold`: each section is an existing command's answer, computed
@@ -25,6 +27,7 @@ interface ScaffoldParts {
 	declared: string
 	cases: ReadonlyArray<string>
 	consumers: string | undefined
+	estimate?: DeclaredSize | undefined
 }
 
 // A body target that names a file is a planned file; any other name is an identifier whose consumers
@@ -94,9 +97,17 @@ function file_sections(parts: ScaffoldParts): ReadonlyArray<string> {
 	]
 }
 
+function estimate_lines(size: DeclaredSize | undefined): Array<string> {
+	if (size === undefined) return []
+	const counts = issue_body_keys.size_value(String(size.files), String(size.lines))
+
+	return [`${issue_body_keys.prefix('size')} ${counts}`]
+}
+
 function format(parts: ScaffoldParts): string {
 	return [
 		parts.summary,
+		...estimate_lines(parts.estimate),
 		...file_sections(parts),
 		section(
 			'plan:consumers',

package/scripts/release/github-release-notes.ts

@@ -0,0 +1,24 @@
+// GitHub refuses a release whose body exceeds this many characters (HTTP 422).
+const MAX_BODY_LENGTH = 125_000
+const LINE_BREAK = '\n'
+
+function changelog_url(repository: string, tag: string, previous: string | undefined): string {
+	const root = `https://github.com/${repository}`
+
+	return previous === undefined ? `${root}/commits/${tag}` : `${root}/compare/${previous}...${tag}`
+}
+
+// Cut at a line break so no Markdown line or surrogate pair is split; the changelog link stays last.
+function cap_body(body: string, url: string): string {
+	if (body.length <= MAX_BODY_LENGTH) return body
+
+	const tail = `${LINE_BREAK}${LINE_BREAK}…${LINE_BREAK}${LINE_BREAK}**Full Changelog**: ${url}`
+	const head = body.slice(0, MAX_BODY_LENGTH - tail.length)
+	const line_end = head.lastIndexOf(LINE_BREAK)
+
+	return `${line_end > 0 ? head.slice(0, line_end) : head}${tail}`
+}
+
+const github_release_notes = { MAX_BODY_LENGTH, cap_body, changelog_url }
+
+export { github_release_notes }

package/scripts/release/github-release-runs.ts

@@ -21,6 +21,11 @@ const JOBS_SCHEMA = z.object({ jobs: z.array(JOB_SCHEMA) })
 type Run = z.infer<typeof RUN_SCHEMA>
 type PollState = 'ready' | 'failed' | 'pending'
 
+interface JobOutcomes {
+	failed: ReadonlyArray<string>
+	succeeded: ReadonlyArray<string>
+}
+
 // `read` answers a GET on a repository API path. `workflow` is the publish workflow and `jobs` the
 // jobs in it whose failure counts (empty: every job). `release_run_workflow` is the workflow that
 // creates a tag's release — the publish workflow itself when its run creates the release.
@@ -31,11 +36,15 @@ interface RunSource {
 	release_run_workflow: string | undefined
 }
 
+// A reusable workflow's jobs are listed as `<caller job> / <job>`, so the caller's name covers them.
+function is_named_job(job_name: string, names: ReadonlyArray<string>): boolean {
+	return names.some((name) => job_name === name || job_name.startsWith(`${name} /`))
+}
+
 function is_failed_job(job: z.infer<typeof JOB_SCHEMA>, names: ReadonlyArray<string>): boolean {
 	if (job.status !== 'completed' || !FAILED_CONCLUSIONS.has(job.conclusion ?? '')) return false
-	if (names.length === 0) return true
 
-	return names.some((name) => job.name === name || job.name.startsWith(`${name} /`))
+	return names.length === 0 || is_named_job(job.name, names)
 }
 
 async function list_runs(source: RunSource, workflow_name: string): Promise<ReadonlyArray<Run>> {
@@ -55,12 +64,22 @@ async function find_run(
 	return runs.find((item) => item.display_title === title)
 }
 
-async function has_failed_job(source: RunSource, run_id: number): Promise<boolean> {
+// A job skipped because the one it needs failed is in neither list.
+async function job_outcomes(source: RunSource, run_id: number): Promise<JobOutcomes> {
 	const { jobs } = JOBS_SCHEMA.parse(
 		await source.read(`/actions/runs/${String(run_id)}/jobs?per_page=100`),
 	)
 
-	return jobs.some((job) => is_failed_job(job, source.jobs))
+	return {
+		failed: jobs.filter((job) => is_failed_job(job, source.jobs)).map((job) => job.name),
+		succeeded: jobs.filter((job) => job.conclusion === 'success').map((job) => job.name),
+	}
+}
+
+async function has_failed_job(source: RunSource, run_id: number): Promise<boolean> {
+	const { failed } = await job_outcomes(source, run_id)
+
+	return failed.length > 0
 }
 
 // A run started before its title named the tag may be at work on any tag.
@@ -120,7 +139,14 @@ async function publication_state(
 	return run_state(await publish_run(source, workflow, tag))
 }
 
-const github_release_runs = { is_release_lost, publication_state, publish_run, run_state }
+const github_release_runs = {
+	is_named_job,
+	job_outcomes,
+	is_release_lost,
+	publication_state,
+	publish_run,
+	run_state,
+}
 
-export type { PollState, Run, RunSource }
+export type { JobOutcomes, PollState, Run, RunSource }
 export { github_release_runs }

package/scripts/release/github-release.ts

@@ -2,6 +2,7 @@ import { setTimeout } from 'node:timers/promises'
 import { poll as shared_poll } from '#scripts/lib/poll'
 import semver from 'semver'
 import { z } from 'zod'
+import { github_release_notes } from './github-release-notes'
 import { github_release_runs, type PollState, type RunSource } from './github-release-runs'
 
 const API_ROOT = 'https://api.github.com/repos'
@@ -41,6 +42,7 @@ interface Client extends Omit<RunSource, 'read'> {
 	request: ReleaseRequest
 	token: string
 	url: string
+	repository: string
 }
 
 // `fallback` answers when no tag sits between the floor and the target; without one the floor itself
@@ -81,7 +83,11 @@ async function api_post(client: Client, path: string, body: object): Promise<Res
 }
 
 async function read_response(response: Response): Promise<unknown> {
-	if (!response.ok) throw new Error(`GitHub Releases API returned HTTP ${String(response.status)}`)
+	if (!response.ok) {
+		const detail = await response.text()
+
+		throw new Error(`GitHub Releases API returned HTTP ${String(response.status)}: ${detail}`)
+	}
 
 	return await response.json()
 }
@@ -248,10 +254,11 @@ async function create_release(
 	previous: string | undefined,
 ): Promise<void> {
 	const notes = await generate_notes(client, tag, previous)
+	const url = github_release_notes.changelog_url(client.repository, tag, previous)
 	const response = await api_post(client, '/releases', {
 		tag_name: tag,
 		name: notes.name,
-		body: notes.body,
+		body: github_release_notes.cap_body(notes.body, url),
 		draft: false,
 		prerelease: false,
 	})
@@ -268,6 +275,7 @@ function create_client(request: ReleaseRequest, token: string, settings: Release
 		request,
 		token,
 		url: `${API_ROOT}/${settings.repository}`,
+		repository: settings.repository,
 		workflow: settings.workflow,
 		jobs: settings.jobs ?? [],
 		release_run_workflow: settings.release_run_workflow,

package/scripts/release/release-progress.ts

@@ -4,7 +4,7 @@ import { git_gh_exec } from '#scripts/gh/git-gh-exec'
 import { poll } from '#scripts/lib/poll'
 import { file_reader } from '#scripts/lib/read-file'
 import { npm_registry } from '#scripts/version/npm-registry'
-import { release_publish_run } from './release-publish-run'
+import { release_publish_run, type FailedRun } from './release-publish-run'
 import { release_tag } from './release-tag'
 
 // The stage lines `pnpm josh release` prints, and the two stages it waits for after the tag.
@@ -26,7 +26,7 @@ const HTML_URL_FILTER = '.html_url'
 const PUBLISH_WORKFLOW_PATH = '.github/workflows/publish.yml'
 const RELEASE_WORKFLOW_PATH = '.github/workflows/github-release.yml'
 
-type NpmState = { kind: 'published' } | { kind: 'failed'; run_id: number } | { kind: 'pending' }
+type NpmState = { kind: 'published' } | { kind: 'failed'; run: FailedRun } | { kind: 'pending' }
 
 function pr_opened_line(pr_url: string): string {
 	return `📝 Release PR opened: ${pr_url}`
@@ -61,15 +61,27 @@ function missed_npm_line(package_name: string, version: string): string {
 	].join('\n')
 }
 
+function failed_run_headline(tag: string, run: FailedRun): string {
+	const run_label = `Publish ${tag} failed (run ${String(run.run_id)})`
+
+	if (run.has_npm_job_failed) return `❌ ${run_label} before npm listed ${tag}.`
+
+	return `❌ ${run_label} in ${run.failed_jobs.join(', ')}; its publish-npm job succeeded.`
+}
+
 // The run's own failure is known, so the line names the run rather than a stage that never came. It
-// claims no more than the last registry read: a job beside `publish-npm` can fail the run after npm
-// took the version.
-function failed_publish_line(version: string, run_id: number): string {
+// claims no more than the last registry read: when a job beside `publish-npm` failed the run, npm
+// may still take the version, so the npm side is reported as unconfirmed rather than failed.
+function failed_publish_line(package_name: string, version: string, run: FailedRun): string {
 	const tag = release_tag.tag_name(version)
+	const npm_lines = run.has_npm_job_failed
+		? []
+		: [`  npm has not listed ${tag} yet: check ${npm_package_url(package_name, version)}`]
 
 	return [
-		`❌ Publish ${tag} failed (run ${String(run_id)}) before npm listed ${tag}.`,
-		`  Inspect it with: gh run view ${String(run_id)} --log-failed`,
+		failed_run_headline(tag, run),
+		...npm_lines,
+		`  Inspect it with: gh run view ${String(run.run_id)} --log-failed`,
 	].join('\n')
 }
 
@@ -117,16 +129,16 @@ async function read_release_url(version: string): Promise<string | undefined> {
 
 function npm_outcome_line(package_name: string, version: string, state: NpmState): string {
 	if (state.kind === 'published') return npm_line(package_name, version)
-	if (state.kind === 'failed') return failed_publish_line(version, state.run_id)
+	if (state.kind === 'failed') return failed_publish_line(package_name, version, state.run)
 
 	return missed_npm_line(package_name, version)
 }
 
 async function npm_state(package_name: string, version: string): Promise<NpmState> {
 	if (npm_registry.has_public_version(package_name, version)) return { kind: 'published' }
-	const run_id = await release_publish_run.failed_run_id(version)
+	const run = await release_publish_run.failed_run(version)
 
-	return run_id === undefined ? { kind: 'pending' } : { kind: 'failed', run_id }
+	return run === undefined ? { kind: 'pending' } : { kind: 'failed', run }
 }
 
 // `josh release` is distributed to consumers whose packages are not on npm, so a repository that does