@joshuafolkken/kit 1.1050.0 → 1.1128.0

package/scripts/epic/epic-read.ts

@@ -1,4 +1,4 @@
-import { git_gh_command } from '#scripts/git/git-gh-command'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { epic_fetch } from './epic-fetch'
 import { epic_graph, type EpicChild } from './epic-graph'
 import { epic_parse } from './epic-parse'
@@ -65,7 +65,6 @@ async function read_epic(epic_number: number): Promise<EpicReading | { error: st
 }
 
 const epic_read = {
-	UNKNOWN_REPO,
 	read_epic,
 }
 

package/scripts/epic/epic-reconcile.ts

@@ -1,4 +1,4 @@
-import { git_gh_command } from '#scripts/git/git-gh-command'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { epic_add_body } from './epic-add-body'
 import { epic_chains } from './epic-chains'
 import { epic_graph, type EpicChild, type IssueReference } from './epic-graph'

package/scripts/epic/epic-reference.ts

@@ -54,20 +54,8 @@ function format_replaced_relations(links: ReadonlyArray<DependencyLink>): string
 	return `Replaced blocked-by: ${join_references(quoted)}.`
 }
 
-const epic_reference = {
-	DEPENDENCY_ARROW,
-	REFERENCE_SEPARATOR,
-	to_issue_reference,
-	join_references,
-	format_dependency_link,
-	format_dependency_links,
-	format_issue_references,
-	format_replaced_relations,
-}
-
-export type { IssueReference } from '#scripts/git/issue-reference'
+export type { IssueReference } from '#scripts/issue/issue-reference'
 export {
-	epic_reference,
 	DEPENDENCY_ARROW,
 	REFERENCE_SEPARATOR,
 	to_issue_reference,

package/scripts/epic/epic-relation-recheck.ts

@@ -103,7 +103,7 @@ async function recheck_missing_relations(
 	)
 }
 
-const epic_relation_recheck = { recheck_missing_relations, suspect_children, RECHECK_LIMIT }
+const epic_relation_recheck = { recheck_missing_relations, RECHECK_LIMIT }
 
 export type { BlockersReader }
 export { epic_relation_recheck }

package/scripts/epic/epic-relations.ts

@@ -1,4 +1,4 @@
-import { git_gh_command } from '#scripts/git/git-gh-command'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
 import type { DependencyLink } from './epic-parse'
 import { format_dependency_links } from './epic-reference'
 

package/scripts/epic/epic-remove.ts

@@ -1,4 +1,4 @@
-import { git_gh_command } from '#scripts/git/git-gh-command'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { epic_decision } from './epic-decision'
 import { epic_read } from './epic-read'
 import { format_dependency_links } from './epic-reference'

package/scripts/epic/epic-report.ts

@@ -193,7 +193,6 @@ const epic_report = {
 	build_result,
 	candidates_for_repo,
 	format_result,
-	VERDICT_LINES,
 }
 
 export type { EpicNextResult, EpicVerdict, RepoCandidates }

package/scripts/epic/epic-run.ts

@@ -1,5 +1,5 @@
-import { git_gh_command } from '#scripts/git/git-gh-command'
-import { EPIC_LABEL } from '#scripts/git/issue-labels'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { EPIC_LABEL } from '#scripts/issue/issue-labels'
 import { epic_body } from './epic-body'
 import { epic_promote } from './epic-promote'
 import { epic_relations } from './epic-relations'
@@ -213,7 +213,6 @@ async function check_epic(epic_number: number): Promise<number> {
 }
 
 const epic_run = {
-	parse_created_number,
 	create_epic,
 	promote_epic,
 	check_epic,

package/scripts/epic/epic-shape.ts

@@ -1,4 +1,4 @@
-import { EPIC_LABEL } from '#scripts/git/issue-labels'
+import { EPIC_LABEL } from '#scripts/issue/issue-labels'
 import { epic_parse } from './epic-parse'
 import { to_issue_reference } from './epic-reference'
 

package/scripts/epic/epic-solo-stale.ts

@@ -0,0 +1,107 @@
+import { setTimeout as sleep } from 'node:timers/promises'
+import type { OpenIssueData } from '#scripts/git/schemas'
+import { has_any_label, IN_PROGRESS_LABEL, RUN_SOLO_LABEL } from '#scripts/issue/issue-labels'
+import { lane_await } from '#scripts/lane/lane-await'
+import { lane_registry } from '#scripts/lane/lane-registry'
+import { issue_citation } from '#scripts/rules/issue-citation'
+import type { BusyRead } from './epic-busy'
+
+// A `run:solo` holder nothing is running for (joshuafolkken/kit#3017).
+//
+// A running `run:solo` issue lets nothing new start (`epic-solo.ts`), and "running" is read off the
+// `in-progress` label alone. A label nothing removed — a child that parked itself, then had its
+// `needs-decision` lifted by a person — therefore held the whole backlog: every candidate went to
+// `waiting`, no lane was running to release it, and `backlog:offer` booked the run `exhausted`.
+//
+// **What decides it is the child's process, not its lane.** The lane of a child that parked itself
+// stays open after the child has ended, so an open lane is no evidence of a run; the process pattern
+// `lane:await` and `run:liveness` read is. A matching process keeps the holder, whatever its lane.
+//
+// **A missing process releases only what this machine dispatched, and only once re-confirmed.** The
+// process read sees this machine alone, and a session a person started by hand matches no lane
+// pattern, so an absent process is evidence of an ended run only for a holder with a lane here. A
+// boundary cut drops the process for a moment before its resume takes over, so the absence is read
+// again after `lane_await.RECONFIRM_MS` — the window `lane:await` measured for that handoff. Every
+// doubt keeps the holder: a wrongly kept label waits, a wrongly released one runs beside a solo run.
+//
+// Only `run:solo` holders are released: theirs is the one label that blocks every candidate. A stale
+// ordinary holder spends one lane, which `epic_busy.lanes_full_message` already names.
+
+const SOLO_LABELS: ReadonlySet<string> = new Set([RUN_SOLO_LABEL])
+
+interface StaleRelease {
+	read: BusyRead
+	notice?: string
+}
+
+function is_absent_solo(issue: OpenIssueData): boolean {
+	if (!has_any_label(issue.labels, SOLO_LABELS)) return false
+
+	return !lane_await.is_process_running_default(String(issue.number))
+}
+
+// The issue numbers of this checkout's lanes. A listing that cannot be read names none, which keeps
+// every holder.
+async function local_lanes(): Promise<ReadonlySet<string>> {
+	try {
+		const lanes = await lane_registry.list_lanes()
+
+		return new Set(lanes.map((lane) => lane.issue))
+	} catch {
+		return new Set()
+	}
+}
+
+async function settle(): Promise<void> {
+	await sleep(lane_await.RECONFIRM_MS)
+}
+
+// Read through this object so a test can stand in for the git listing and the re-confirm wait.
+const io = { local_lanes, settle }
+
+async function find_stale(
+	issues: ReadonlyArray<OpenIssueData>,
+): Promise<ReadonlyArray<OpenIssueData>> {
+	const absent = issues.filter((issue) => is_absent_solo(issue))
+
+	if (absent.length === 0) return []
+
+	const lanes = await io.local_lanes()
+	const dispatched = absent.filter((issue) => lanes.has(String(issue.number)))
+
+	if (dispatched.length === 0) return []
+
+	await io.settle()
+
+	return dispatched.filter((issue) => is_absent_solo(issue))
+}
+
+function stale_message(stale: ReadonlyArray<OpenIssueData>, repo: string): string {
+	const named = stale.map((issue) => `#${String(issue.number)}`).join(', ')
+
+	return issue_citation.linkify(
+		`${named} carries \`${RUN_SOLO_LABEL}\` and \`${IN_PROGRESS_LABEL}\`, but no process of it is running in ${repo} — the \`${IN_PROGRESS_LABEL}\` label is stale, so it does not hold the backlog. Remove the label once you have confirmed nothing is running it.`,
+		repo,
+	)
+}
+
+// The read with every stale `run:solo` holder taken out, and the sentence naming them. A read with no
+// holder left is `idle`, exactly as `epic_busy.parse_listing` answers an empty listing.
+async function release(read: BusyRead, repo: string): Promise<StaleRelease> {
+	if (read.kind !== 'busy') return { read }
+
+	const stale = await find_stale(read.issues)
+
+	if (stale.length === 0) return { read }
+
+	const holders = read.issues.filter((issue) => !stale.includes(issue))
+	const released: BusyRead =
+		holders.length > 0 ? { kind: 'busy', issues: holders } : { kind: 'idle' }
+
+	return { read: released, notice: stale_message(stale, repo) }
+}
+
+const epic_solo_stale = { io, release }
+
+export type { StaleRelease }
+export { epic_solo_stale }

package/scripts/epic/epic-solo.ts

@@ -1,4 +1,4 @@
-import { has_any_label, has_label_name, RUN_SOLO_LABEL } from '#scripts/git/issue-labels'
+import { has_any_label, has_label_name, RUN_SOLO_LABEL } from '#scripts/issue/issue-labels'
 import { issue_citation } from '#scripts/rules/issue-citation'
 import { epic_busy, type BusyRead } from './epic-busy'
 import type { EpicChild } from './epic-graph'
@@ -15,7 +15,8 @@ import { epic_report, type EpicNextResult } from './epic-report'
 // `epic:next --lanes` (a named epic's children, `epic-lane-offer.ts`). One rule, so the two cannot
 // disagree about what may start beside what.
 //
-// Three rules, all against the repository's `in-progress` holders (`epic_busy.read_repository`):
+// Three rules, all against the repository's `in-progress` holders (`epic_busy.read_repository`, with
+// a stale `run:solo` holder taken out by `epic_solo_stale.release` — joshuafolkken/kit#3017):
 // a running `run:solo` issue lets nothing new start; a `run:solo` candidate starts only into an idle
 // repository and then alone; and nothing ranked below a waiting `run:solo` candidate is offered past
 // it, so it is not starved by the lanes it is waiting on. A listing that could not be read is not an

package/scripts/epic/epic-triage.ts

@@ -1,4 +1,4 @@
-import { has_label_name, RUN_LANE_LABEL, RUN_SOLO_LABEL } from '#scripts/git/issue-labels'
+import { has_label_name, RUN_LANE_LABEL, RUN_SOLO_LABEL } from '#scripts/issue/issue-labels'
 import { issue_citation } from '#scripts/rules/issue-citation'
 import type { EpicChild } from './epic-graph'
 

package/scripts/epic/epic-validate.ts

@@ -1,6 +1,6 @@
-import { EPIC_LABEL, has_label_name } from '#scripts/git/issue-labels'
 import { parse_json_object_safe } from '#scripts/git/parse-json-array'
 import { epic_subject_schema } from '#scripts/git/schemas'
+import { EPIC_LABEL, has_label_name } from '#scripts/issue/issue-labels'
 import { epic_parse, type DeclarationState } from './epic-parse'
 
 // The four requirements an epic has to satisfy are otherwise enforced only by an agent reading the

package/scripts/epic/epic.ts

@@ -9,7 +9,7 @@
  *                                                      [--decision-file <path|->]
  *        tsx scripts/epic/epic.ts --remove <E> <M> <N> ... [--decision-file <path|->]
  */
-import { git_gh_command } from '#scripts/git/git-gh-command'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { error_text } from '#scripts/lib/error-message'
 import { epic_add, type AddChildrenInput } from './epic-add'
 import { epic_cli, type AddArguments, type CrossRepoAddTarget } from './epic-cli'

package/scripts/exports/unused-members-cli.ts

@@ -0,0 +1,53 @@
+#!/usr/bin/env tsx
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { doctor_consumer } from '#scripts/doctor/doctor-consumer'
+import { project_checks } from '#scripts/gate/project-checks'
+import type { NamespaceMember } from './namespace-members'
+
+const CHECK = 'exports'
+const FAIL_EXIT_CODE = 1
+// A consumer's namespaces are read from `.svelte` files and routes a TypeScript program over its
+// `tsconfig.json` does not see, so every member they use would read as unused. The check is kit's own.
+const CONSUMER_SKIP_REASON = 'checks only the kit repository itself, not a consumer project'
+
+function format_member(root: string, member: NamespaceMember): string {
+	return `${path.relative(root, member.file)}:${String(member.line)}  ${member.namespace}.${member.member}`
+}
+
+function report(root: string, members: ReadonlyArray<NamespaceMember>): string {
+	if (members.length === 0) return `josh ${CHECK}: no unused namespace member`
+
+	return [
+		`josh ${CHECK}: ${String(members.length)} namespace member(s) nothing reads — remove each from its namespace object (and the declaration, if nothing in its file uses it either):`,
+		...members.map((member) => `  ${format_member(root, member)}`),
+	].join('\n')
+}
+
+async function run_unused_members(root: string): Promise<number> {
+	if (doctor_consumer.is_kit_consumer(root)) {
+		console.info(project_checks.skip_notice(CHECK, CONSUMER_SKIP_REASON))
+
+		return 0
+	}
+
+	// Loaded only past the skip: the scanner pulls in `typescript`, an optional peer a basic-profile
+	// consumer may not have, and this check runs in every consumer's gate. For the same reason the
+	// scanner is left out of the published package (`package.json` `files`); only this entry ships.
+	const { unused_members } = await import('./unused-members')
+	const members = unused_members.find_unused_members(root)
+	const output = report(root, members)
+
+	if (members.length === 0) console.info(output)
+	else console.error(output)
+
+	return members.length === 0 ? 0 : FAIL_EXIT_CODE
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	process.exitCode = await run_unused_members(project_checks.project_root(process.cwd()))
+}
+
+const unused_members_cli = { run_unused_members }
+
+export { unused_members_cli }

package/scripts/{git → followup}/followup-issue-number.ts

@@ -23,9 +23,4 @@ function parse_completed_issue_number(raw: string | undefined): number | undefin
 	return digits === undefined ? undefined : Number(digits)
 }
 
-const followup_issue_number = {
-	parse_issue_number_from_text,
-	parse_completed_issue_number,
-}
-
-export { followup_issue_number, parse_issue_number_from_text, parse_completed_issue_number }
+export { parse_issue_number_from_text, parse_completed_issue_number }

package/scripts/{git → followup}/git-followup-cleanup.ts

@@ -1,4 +1,4 @@
-import { git_gh_helpers } from './git-gh-helpers'
+import { git_gh_helpers } from '#scripts/gh/git-gh-helpers'
 
 // joshuafolkken/kit#1539: everything a run does after its merge is cleanup, and a merge cannot be
 // taken back. Those steps used to be plain sequential statements, so whichever of them threw first
@@ -70,6 +70,7 @@ async function run_guarded_steps(
 	let is_complete = true
 
 	for (const step of steps) {
+		// eslint-disable-next-line no-await-in-loop -- cleanup steps run in their declared order
 		const is_done = await run_guarded_step(is_guarded, step)
 
 		if (!is_done) is_complete = false

package/scripts/{git → followup}/git-followup-finish.ts

@@ -1,3 +1,4 @@
+import { git_next_issues } from '#scripts/issue/git-next-issues'
 import { review_attest } from '#scripts/review/review-attest'
 import { review_stamps } from '#scripts/review/review-stamps'
 import { run_hold } from '#scripts/run/run-hold'
@@ -5,7 +6,6 @@ import { run_progress_clock } from '#scripts/run/run-progress-clock'
 import { parse_completed_issue_number } from './followup-issue-number'
 import { git_followup_cleanup, type CleanupStep } from './git-followup-cleanup'
 import { git_followup_pending } from './git-followup-pending'
-import { git_next_issues } from './git-next-issues'
 
 // **The count of unreleased merges, not the project version** (joshuafolkken/kit#1486). This line
 // used to read the local `package.json` and was read as "the version this run just shipped"; children
@@ -208,8 +208,6 @@ const git_followup_finish = {
 	print_next_issues,
 	print_pending_release,
 	clear_review_records,
-	clear_round_one_snapshot,
-	clear_review_target,
 	release_worktree_hold,
 	end_progress_watcher,
 }

package/scripts/{git → followup}/git-followup-flush.ts

@@ -1,8 +1,8 @@
+import { git_command } from '#scripts/git/git-command'
+import { git_spawn } from '#scripts/git/git-spawn'
 import { observation_ledger } from '#scripts/observations/observation-ledger'
 import { observation_ledger_prepare } from '#scripts/observations/observation-ledger-prepare'
 import { observations_flush } from '#scripts/observations/observations-flush'
-import { git_command } from './git-command'
-import { git_spawn } from './git-spawn'
 
 // The residual commit path for the observation ledger (joshuafolkken/kit#1810). A run's appended lines
 // ride its own commit (joshuafolkken/kit#2763), so the ledger is usually clean by now and this

package/scripts/{git → followup}/git-followup-issue-close.ts

@@ -1,8 +1,8 @@
 import { epic_parse } from '#scripts/epic/epic-parse'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { parse_json_object_safe } from '#scripts/git/parse-json-array'
 import { poll, type PollOptions } from '#scripts/lib/poll'
 import { z } from 'zod'
-import { git_gh_command } from './git-gh-command'
-import { parse_json_object_safe } from './parse-json-array'
 
 // **A merged pull request whose `closes #N` GitHub did not apply** (joshuafolkken/kit#2770). From
 // 2026-09-30 06:34Z every merge `followup` made left its issue open — seven in a row, where every

package/scripts/{git → followup}/git-followup-label.ts

@@ -1,8 +1,8 @@
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { parse_json_object_safe } from '#scripts/git/parse-json-array'
+import { issue_label_schema } from '#scripts/git/schemas'
+import { IN_PROGRESS_LABEL, label_name_of } from '#scripts/issue/issue-labels'
 import { z } from 'zod'
-import { git_gh_command } from './git-gh-command'
-import { IN_PROGRESS_LABEL, label_name_of } from './issue-labels'
-import { parse_json_object_safe } from './parse-json-array'
-import { issue_label_schema } from './schemas'
 
 // **`in-progress` means "a run is holding this issue right now", and a merged run is not holding
 // anything** (joshuafolkken/kit#1794). `pnpm josh followup` merged the pull request and closed the

package/scripts/followup/git-followup-merged.ts

@@ -0,0 +1,112 @@
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import type { PullMergeState } from '#scripts/gh/git-gh-pr-read'
+import { json_value } from '#scripts/lib/json-value'
+import { z } from 'zod'
+
+// joshuafolkken/kit#3023: `prrun` stops at a green, mergeable pull request and a person merges it by
+// hand. Re-running `pnpm josh followup` then has to finish what a merged `fullrun` finishes — the
+// completion report, the epic close, the merged issue's close, the `in-progress` removal, the hold
+// release and the completion Telegram — **from the one tail `followup` already runs**, not a copy of
+// it elsewhere: the hold release and `josh ms` act on the local work tree, which CI never sees.
+//
+// **A merged pull request is read, not declared.** No flag says "a person merged this"; `followup`
+// asks the pull request, so the same command works whichever of the two merged it. The merge plan
+// below is what the rest of the run branches on: merged skips every pre-merge step — the review and
+// live-evidence gates, the CI wait, the AI-review scans and the merge call — and runs the tail as a
+// merged run's, even under `--no-merge`, because there is nothing left for that flag to hold back.
+//
+// **A second run must not repeat the report.** Every other tail step is idempotent by nature (a
+// closed epic is not closed twice, a released hold releases nothing), but the completion comment and
+// the completion Telegram are writes that would land again. The comment is the record that the tail
+// already ran: a `✅` report naming this pull request, **posted on the issue at or after the merge**.
+// The time is what tells it apart from the report the `prrun` stop itself posted — a `--no-merge`
+// run's tail posts the same `✅` report naming the same pull request before anything merged, and
+// reading that one as the merged run's would skip the only report that says it merged. A report the
+// tail wrote into a blank issue body carries no time, so it is not counted: a re-run then posts it
+// once more as a comment, the cheaper failure than a merged run that reported nothing.
+
+interface MergePlan {
+	is_merged: boolean
+	should_merge: boolean
+	merged_at: string | undefined
+}
+
+const COMPLETION_MARK = '✅ '
+const PR_LINE_PREFIX = 'PR: '
+const LINE_SEPARATOR = '\n'
+
+const COMMENTS_SCHEMA = z.array(
+	z.object({ body: z.string().nullish(), created_at: z.string().nullish() }),
+)
+
+type IssueComment = z.infer<typeof COMMENTS_SCHEMA>[number]
+
+function to_merge_plan(state: PullMergeState | undefined, is_merge_requested: boolean): MergePlan {
+	const is_merged = state?.is_merged === true
+
+	return { is_merged, should_merge: is_merged || is_merge_requested, merged_at: state?.merged_at }
+}
+
+async function read_merge_plan(
+	branch_name: string,
+	is_merge_requested: boolean,
+): Promise<MergePlan> {
+	return to_merge_plan(await git_gh_command.pr_get_merge_state(branch_name), is_merge_requested)
+}
+
+function is_completion_text(text: string | null | undefined, pr_url: string): boolean {
+	if (typeof text !== 'string' || !text.startsWith(COMPLETION_MARK)) return false
+
+	return text.split(LINE_SEPARATOR).includes(`${PR_LINE_PREFIX}${pr_url}`)
+}
+
+function is_posted_since(comment: IssueComment, merged_at: string): boolean {
+	if (typeof comment.created_at !== 'string') return false
+
+	return Date.parse(comment.created_at) >= Date.parse(merged_at)
+}
+
+function parse_comments(comments_json: string | undefined): Array<IssueComment> {
+	const parsed = COMMENTS_SCHEMA.safeParse(json_value.parse_or_undefined(comments_json ?? ''))
+
+	return parsed.success ? parsed.data : []
+}
+
+// The pure half: whether one of the issue's comments is this pull request's report, posted since it merged.
+function has_completion_record(input: {
+	comments_json: string | undefined
+	pr_url: string
+	merged_at: string
+}): boolean {
+	return parse_comments(input.comments_json).some(
+		(comment) =>
+			is_completion_text(comment.body, input.pr_url) && is_posted_since(comment, input.merged_at),
+	)
+}
+
+// Asked only on a merged pull request: an unmerged run has never reached the tail, so its report
+// cannot be there yet. **An unreadable issue reads as "not recorded"** — the tail then posts, and a
+// duplicate report is the cheaper failure than a merged run that reported nothing.
+async function is_completion_recorded(input: {
+	merged_at: string | undefined
+	issue_number: string | undefined
+	pr_url: string | undefined
+}): Promise<boolean> {
+	const { merged_at, issue_number, pr_url } = input
+
+	if (issue_number === undefined || pr_url === undefined || merged_at === undefined) return false
+
+	const comments_json = await git_gh_command.issue_list_comments(issue_number)
+
+	return has_completion_record({ comments_json, pr_url, merged_at })
+}
+
+const git_followup_merged = {
+	has_completion_record,
+	is_completion_recorded,
+	read_merge_plan,
+	to_merge_plan,
+}
+
+export type { MergePlan }
+export { git_followup_merged }

package/scripts/{git → followup}/git-followup-pending.ts

@@ -1,7 +1,7 @@
+import { git_command } from '#scripts/git/git-command'
 import { release_history, type HistoryReader } from '#scripts/release/release-history'
 import { release_plan } from '#scripts/release/release-plan'
 import { version_targets } from '#scripts/version/version-targets'
-import { git_command } from './git-command'
 
 // What the completion notification says about versions, now that children do not set one
 // (joshuafolkken/kit#1486).

package/scripts/{git → followup}/git-followup-workflow.ts

@@ -1,16 +1,17 @@
 #!/usr/bin/env tsx
 import { parseArgs } from 'node:util'
+import { git_branch } from '#scripts/git/git-branch'
+import { git_error } from '#scripts/git/git-error'
 import { cli_body } from '#scripts/josh/cli-body'
 import { josh_environment_file } from '#scripts/josh/josh-environment-file'
+import { git_notify, type GitNotifyConfig } from '#scripts/notify/git-notify'
 import { live_evidence } from '#scripts/review/live-evidence'
 import { review_attest } from '#scripts/review/review-attest'
 import { review_record } from '#scripts/review/review-record'
 import { parse_issue_number_from_text } from './followup-issue-number'
-import { git_branch } from './git-branch'
-import { git_error } from './git-error'
 import { git_followup_finish } from './git-followup-finish'
 import { git_followup_flush } from './git-followup-flush'
-import { git_notify, type GitNotifyConfig } from './git-notify'
+import { git_followup_merged, type MergePlan } from './git-followup-merged'
 import { git_pr_followup } from './git-pr-followup'
 
 josh_environment_file.load_environment_file()
@@ -204,14 +205,18 @@ async function assert_merge_gates(
 }
 
 // After the gates, before the CI wait: a line appended since the run's commit rides the pull request
-// itself, so it merges with it — a lane's included (joshuafolkken/kit#2919).
+// itself, so it merges with it — a lane's included (joshuafolkken/kit#2919). **A pull request that has
+// already merged skips both** (joshuafolkken/kit#3023): the gates guard a merge this run no longer
+// makes, and a ledger commit would land on a branch that has already gone in.
 async function prepare_merge(
-	should_merge: boolean,
+	plan: MergePlan,
 	issue_number: string | undefined,
 	branch_name: string,
 ): Promise<void> {
-	await assert_merge_gates(should_merge, issue_number, branch_name)
-	await git_followup_flush.commit_ledger_step(should_merge, issue_number)
+	if (plan.is_merged) return
+
+	await assert_merge_gates(plan.should_merge, issue_number, branch_name)
+	await git_followup_flush.commit_ledger_step(plan.should_merge, issue_number)
 }
 
 async function main(): Promise<void> {
@@ -225,10 +230,10 @@ async function main(): Promise<void> {
 
 	const issue_number =
 		cli.values['issue-number'] ?? parse_issue_number_from_text(cli.positionals[0] ?? undefined)
-	const should_merge = is_merge_resolved(cli.values)
 	const branch_name = await resolve_branch_name(cli.values.branch)
+	const plan = await git_followup_merged.read_merge_plan(branch_name, is_merge_resolved(cli.values))
 
-	await prepare_merge(should_merge, issue_number, branch_name)
+	await prepare_merge(plan, issue_number, branch_name)
 	// **The number the run reports on is the one it used**, which is the number the pull request
 	// closes where the invocation named none (joshuafolkken/kit#1539). Recovered inside `run`, so the
 	// tail records a run the command line could not identify rather than silently skipping it.
@@ -239,10 +244,12 @@ async function main(): Promise<void> {
 		coderabbit_ignore_reason: cli.values['coderabbit-ignore-reason'],
 		ai_review_ignore_reason: cli.values['ai-review-ignore-reason'],
 		is_skip_watch: cli.values['skip-watch'] === true,
-		should_merge,
+		should_merge: plan.should_merge,
+		is_merged: plan.is_merged,
+		merged_at: plan.merged_at,
 	})
 
-	await git_followup_finish.finish(used_issue_number ?? issue_number, should_merge)
+	await git_followup_finish.finish(used_issue_number ?? issue_number, plan.should_merge)
 }
 
 try {
@@ -257,6 +264,7 @@ const git_followup_workflow = {
 	assert_review_attested,
 	assert_review_recorded,
 	parse_issue_number_from_text,
+	prepare_merge,
 	resolve_branch_name,
 	is_merge_resolved,
 }

package/scripts/{git → followup}/git-pr-followup-wrapup.ts

@@ -1,10 +1,10 @@
 import { epic_close } from '#scripts/epic/epic-close'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { git_notify, type GitNotifyConfig } from '#scripts/notify/git-notify'
 import { git_followup_cleanup } from './git-followup-cleanup'
 import { git_followup_issue_close } from './git-followup-issue-close'
 import { git_followup_label } from './git-followup-label'
 import { git_followup_stages, type StageLog } from './git-followup-stages'
-import { git_gh_command } from './git-gh-command'
-import { git_notify, type GitNotifyConfig } from './git-notify'
 
 const { STAGE, lap } = git_followup_stages
 
@@ -35,6 +35,10 @@ interface WrapupInput {
 	// completion notification (joshuafolkken/kit#1592). Empty on a run that changed nothing `josh sync`
 	// distributes, and an empty one adds no line.
 	managed_notes: ReadonlyArray<string>
+	// A pull request merged before this run is not merged again, and a tail whose completion report is
+	// already on the issue does not post it twice (joshuafolkken/kit#3023, `git-followup-merged.ts`).
+	is_merged?: boolean | undefined
+	is_completion_recorded?: boolean | undefined
 }
 
 function build_notify_body(input: {
@@ -113,6 +117,8 @@ async function post_completion_notification(input: {
 // merge, a step that throws is reported and the ones after it still run, rather than taking the epic
 // close and the working-tree hold release down with it.
 async function notify_step(input: WrapupInput): Promise<void> {
+	if (input.is_completion_recorded === true) return
+
 	await git_followup_cleanup.run_guarded_step(input.should_merge, {
 		label: 'The completion comment',
 		recovery: COMPLETION_COMMENT_RECOVERY,
@@ -227,7 +233,7 @@ async function run_tail_steps(input: WrapupInput): Promise<void> {
 }
 
 async function run_wrapup(input: WrapupInput, log: StageLog): Promise<void> {
-	if (input.should_merge) {
+	if (input.should_merge && input.is_merged !== true) {
 		await git_gh_command.pr_merge(input.branch_name)
 		lap(log, STAGE.merge)
 	}