@joshuafolkken/kit 1.1471.0 → 1.1784.0

package/scripts/epic/epic-classify.ts

@@ -1,9 +1,5 @@
-import {
-	ALREADY_DONE_LABEL,
-	has_label_name,
-	IN_PROGRESS_LABEL,
-	NEEDS_DECISION_LABEL,
-} from '#scripts/issue/issue-labels'
+import { has_label_name, has_parked_label, IN_PROGRESS_LABEL } from '#scripts/issue/issue-labels'
+import { issue_not_before } from '#scripts/issue/issue-not-before'
 import { epic_graph, type EpicChild, type IssueReference } from './epic-graph'
 import { epic_nested } from './epic-nested'
 import {
@@ -48,14 +44,18 @@ function has_label(child: EpicChild, label: string): boolean {
 	return has_label_name(child.labels, label)
 }
 
-// The labels that put a child in `human` on their own. `needs-decision` waits for an answer nobody
-// has given; `already-done` has its answer — the work is merged, and the close that is left is Tier C
-// and so a person's. Neither is resolved by waiting, which is what separates
-// them from `in-progress` below.
-const HUMAN_LABELS: ReadonlyArray<string> = [NEEDS_DECISION_LABEL, ALREADY_DONE_LABEL]
-
+// The park labels (`PARKED_LABELS`) put a child in `human` on their own. `needs-decision` waits for an
+// answer nobody has given; `already-done` has its answer — the work is merged, and the close that is
+// left is Tier C and so a person's; `run:stalled` waits on a person fixing a mechanical cause. None is
+// resolved by waiting, which is what separates them from `in-progress` below.
 function has_human_label(child: EpicChild): boolean {
-	return HUMAN_LABELS.some((label) => has_label(child, label))
+	return has_parked_label(child.labels)
+}
+
+// A child someone else's session is finishing, or one held until its declared start time
+// (joshuafolkken/kit#4007). Either way waiting resolves it.
+function is_waiting(child: EpicChild): boolean {
+	return has_label(child, IN_PROGRESS_LABEL) || !issue_not_before.is_due(child.body)
 }
 
 // What a child is before its dependencies are considered. A parked child is `human` whatever blocks
@@ -71,7 +71,7 @@ function has_human_label(child: EpicChild): boolean {
 function local_category(child: EpicChild): ChildCategory | undefined {
 	if (child.state === CLOSED) return 'done'
 	if (epic_nested.is_nested_epic(child) || has_human_label(child)) return 'human'
-	if (has_label(child, IN_PROGRESS_LABEL)) return 'time'
+	if (is_waiting(child)) return 'time'
 
 	return undefined
 }
@@ -117,8 +117,16 @@ function reset_reported(): void {
 	reported.clear()
 }
 
+// Silenced for a process that draws the withheld blocker itself: `run:board` leads its row with 🙋
+// (joshuafolkken/kit#4292), so the notice would only scribble over the board.
+const silence = { is_muted: false }
+
+function mute_notices(): void {
+	silence.is_muted = true
+}
+
 function report_notice(notice: OutsideNotice): void {
-	if (reported.has(notice.key)) return
+	if (silence.is_muted || reported.has(notice.key)) return
 
 	reported.add(notice.key)
 	console.warn(notice.message)
@@ -282,6 +290,7 @@ function classify_children(
 
 const epic_classify = {
 	resolve_by_state,
+	mute_notices,
 	reset_reported,
 	local_category,
 	classify_children,

package/scripts/epic/epic-cli-argv.ts

@@ -1,4 +1,5 @@
 import type { ParseArgsOptionsConfig } from 'node:util'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { cli_flags } from '#scripts/lib/cli-flags'
 
 // The argument reading every `josh epic` form shares, on top of `cli_flags`.
@@ -94,7 +95,37 @@ function is_value_unusable(argv: ReadonlyArray<string>, flag: string): boolean {
 	)
 }
 
+// Deduplicated because a repeated number would render a duplicate task-list row, and with
+// `--ordered` would ask GitHub to make an issue block itself.
+function to_child_numbers(raw_children: ReadonlyArray<string>): Array<number> {
+	const numbers = raw_children
+		.filter((raw) => issue_number_shape.is_issue_number(raw))
+		.map(Number)
+		.filter((value) => Number.isSafeInteger(value))
+
+	return [...new Set(numbers)]
+}
+
+// `<E> <N1> <N2> …` — the shape `--promote`, `--add` and `--decide` share: an existing issue, then at
+// least one child other than itself.
+function read_epic_children(
+	parsed: EpicArgv,
+): { epic_number: number; children: Array<number> } | undefined {
+	const [raw_epic, ...raw_children] = parsed.positionals
+
+	if (raw_epic === undefined || !issue_number_shape.ISSUE_NUMBER_PATTERN.test(raw_epic)) {
+		return undefined
+	}
+
+	const epic_number = Number(raw_epic)
+	const children = to_child_numbers(raw_children).filter((child) => child !== epic_number)
+
+	return children.length === 0 ? undefined : { epic_number, children }
+}
+
 const epic_cli_argv = {
+	to_child_numbers,
+	read_epic_children,
 	read_form,
 	positionals_of,
 	read_flag_value,

package/scripts/epic/epic-cli-decide.ts

@@ -0,0 +1,42 @@
+import { epic_cli_argv, type FormFlags } from './epic-cli-argv'
+
+// `josh epic --decide <E> <N...> --decision-file <path|->`'s argument rules — a decision about children
+// the epic already tracks, which `--add --decision-file` refuses as an insertion with nothing to add.
+//
+// Its own module for the reason `--remove` has one: `epic-cli.ts` sits at its line ceiling.
+
+const DECIDE_FLAG = '--decide'
+const DECISION_FLAG = '--decision-file'
+const DECIDE_FORM: FormFlags = { switches: [DECIDE_FLAG], value_flags: [DECISION_FLAG] }
+
+interface DecideArguments {
+	epic_number: number
+	children: Array<number>
+	decision_path: string
+}
+
+// Whether the invocation records a decision rather than creating, promoting or editing the epic.
+function is_decision_entry(argv: ReadonlyArray<string>): boolean {
+	return argv.includes(DECIDE_FLAG)
+}
+
+// The record is the whole point of the form, so a missing or unusable `--decision-file` refuses it
+// rather than reading as "nothing to record".
+function parse_decide_arguments(argv: ReadonlyArray<string>): DecideArguments | undefined {
+	if (epic_cli_argv.is_value_unusable(argv, DECISION_FLAG)) return undefined
+	const parsed = epic_cli_argv.read_form(argv, DECIDE_FORM)
+	if (parsed === undefined) return undefined
+	const subject = epic_cli_argv.read_epic_children(parsed)
+	const decision_path = epic_cli_argv.read_flag_value(parsed, DECISION_FLAG)
+	if (subject === undefined || decision_path === undefined) return undefined
+
+	return { ...subject, decision_path }
+}
+
+const epic_cli_decide = {
+	is_decision_entry,
+	parse_decide_arguments,
+}
+
+export { epic_cli_decide, DECIDE_FLAG }
+export type { DecideArguments }

package/scripts/epic/epic-cli.ts

@@ -3,6 +3,7 @@ import { session_cite } from '#scripts/issue/session-cite'
 import { cli_body } from '#scripts/josh/cli-body'
 import type { InsertKind, InsertPosition } from './epic-chains'
 import { epic_cli_argv, type EpicArgv, type FormFlags } from './epic-cli-argv'
+import { epic_cli_decide } from './epic-cli-decide'
 import { epic_cli_remove } from './epic-cli-remove'
 import { epic_parse, type ExternalChild } from './epic-parse'
 
@@ -64,17 +65,6 @@ interface PromoteArguments {
 	origin?: string | undefined
 }
 
-// Deduplicated because a repeated number would render a duplicate task-list row, and with
-// `--ordered` would ask GitHub to make an issue block itself.
-function to_child_numbers(raw_children: ReadonlyArray<string>): Array<number> {
-	const numbers = raw_children
-		.filter((raw) => issue_number_shape.is_issue_number(raw))
-		.map(Number)
-		.filter((value) => Number.isSafeInteger(value))
-
-	return [...new Set(numbers)]
-}
-
 // The flags a creation and a promotion share, read the same way for both.
 function read_batch_flags(
 	parsed: EpicArgv,
@@ -90,7 +80,7 @@ function to_create_arguments(parsed: EpicArgv): CreateArguments | undefined {
 	const [title, ...raw_children] = parsed.positionals
 	if (title === undefined || title.length === 0) return undefined
 
-	const children = to_child_numbers(raw_children)
+	const children = epic_cli_argv.to_child_numbers(raw_children)
 	if (children.length === 0) return undefined
 
 	return { title, children, ...read_batch_flags(parsed) }
@@ -134,17 +124,9 @@ function parse_reconcile_arguments(argv: ReadonlyArray<string>): ReconcileArgume
 // positional is a child. Refused when the epic would also be listed as its own child, which would
 // have it block itself under `--ordered`.
 function to_promote_arguments(parsed: EpicArgv): PromoteArguments | undefined {
-	const [raw_epic, ...raw_children] = parsed.positionals
-
-	if (raw_epic === undefined || !issue_number_shape.ISSUE_NUMBER_PATTERN.test(raw_epic)) {
-		return undefined
-	}
-
-	const epic_number = Number(raw_epic)
-	const children = to_child_numbers(raw_children).filter((child) => child !== epic_number)
-	if (children.length === 0) return undefined
+	const subject = epic_cli_argv.read_epic_children(parsed)
 
-	return { epic_number, children, ...read_batch_flags(parsed) }
+	return subject === undefined ? undefined : { ...subject, ...read_batch_flags(parsed) }
 }
 
 function parse_promote_arguments(argv: ReadonlyArray<string>): PromoteArguments | undefined {
@@ -250,23 +232,8 @@ function is_decision_path_unusable(argv: ReadonlyArray<string>): boolean {
 	return is_value_unusable(argv, DECISION_FLAG)
 }
 
-function read_add_subject(
-	parsed: EpicArgv,
-): { epic_number: number; children: Array<number> } | undefined {
-	const [raw_epic, ...raw_children] = parsed.positionals
-
-	if (raw_epic === undefined || !issue_number_shape.ISSUE_NUMBER_PATTERN.test(raw_epic)) {
-		return undefined
-	}
-
-	const epic_number = Number(raw_epic)
-	const children = to_child_numbers(raw_children).filter((child) => child !== epic_number)
-
-	return children.length === 0 ? undefined : { epic_number, children }
-}
-
 function to_add_arguments(parsed: EpicArgv): AddArguments | undefined {
-	const subject = read_add_subject(parsed)
+	const subject = epic_cli_argv.read_epic_children(parsed)
 	if (subject === undefined) return undefined
 	const outcome = parse_position(parsed)
 	if (outcome.is_refused) return undefined
@@ -394,6 +361,7 @@ const epic_cli = {
 	is_addition,
 	is_reconciliation,
 	...epic_cli_remove,
+	...epic_cli_decide,
 	find_cross_repo_add_target,
 	is_decision_path_unusable,
 	resolve_local_add,

package/scripts/epic/epic-close.ts

@@ -1,5 +1,10 @@
 import { git_gh_command } from '#scripts/gh/git-gh-command'
-import { epic_child_schema, epic_issue_schema, type EpicChildData } from '#scripts/git/git-schemas'
+import {
+	epic_child_schema,
+	epic_issue_schema,
+	type EpicChildData,
+	type EpicIssueData,
+} from '#scripts/git/git-schemas'
 import { cutoff_cause, cutoff_of, type ScanCutoff } from '#scripts/git/listing-cutoff'
 import {
 	parse_json_array_or_undefined,
@@ -37,6 +42,7 @@ interface EpicIssue {
 	children: Array<number>
 	external_children: Array<ExternalChild>
 	has_declared_order: boolean
+	is_reopened: boolean
 }
 
 interface SiblingState {
@@ -44,8 +50,12 @@ interface SiblingState {
 	has_blocked_by: boolean
 }
 
-function to_epic_issue(raw: { number: number; body?: string | undefined }): EpicIssue {
+// GitHub's `state_reason` for an open issue that was closed once and reopened.
+const REOPENED = 'reopened'
+
+function to_epic_issue(raw: EpicIssueData): EpicIssue {
 	return {
+		is_reopened: raw.stateReason === REOPENED,
 		number: raw.number,
 		children: epic_parse.parse_task_list_issue_numbers(raw.body),
 		external_children: epic_parse.parse_external_task_list_children(raw.body),
@@ -98,30 +108,32 @@ function to_sibling_state(raw_json: string | undefined): SiblingState {
 	}
 }
 
-async function inspect_sibling(sibling: number, repo?: string): Promise<SiblingState> {
-	return to_sibling_state(await git_gh_command.issue_get_state_and_relations(String(sibling), repo))
-}
+type ChildRead = SiblingState & { is_readable: boolean }
 
-// A cross-repository child, read by naming its repository in the read's REST path. `is_readable`
-// is what decides whether the epic may close at all: closing while a child's state is unknown is
-// exactly what the old refusal prevented, and reading them is the only thing that changed.
-async function inspect_external(
-	child: ExternalChild,
-): Promise<SiblingState & { is_readable: boolean }> {
+// A same-repository child carries no `repo`; a cross-repository one names it.
+type ChildReference = Omit<ExternalChild, 'repo'> & { repo?: string | undefined }
+
+// A child read by number, naming its repository in the REST path when it lives in another one.
+// `is_readable` is what decides whether the epic may close at all: closing while a child's state is
+// unknown is exactly what the refusal prevents. A failed read is told apart from an open child
+// rather than read as one, which left a finished epic open with nothing in the output (#4560). A
+// read whose answer carries no state is a failed read too.
+async function inspect_child(child: ChildReference): Promise<ChildRead> {
 	const raw = await git_gh_command.issue_get_state_and_relations(String(child.number), child.repo)
 
-	return { ...to_sibling_state(raw), is_readable: raw !== undefined }
+	return { ...to_sibling_state(raw), is_readable: parse_child(raw)?.state !== undefined }
 }
 
 // The merged Issue is excluded rather than queried: GitHub applies `closes #N` asynchronously, so
 // reading its state immediately after the merge races with that propagation.
-async function inspect_siblings(
-	epic: EpicIssue,
-	merged_number: number,
-): Promise<Array<SiblingState>> {
-	const siblings = epic.children.filter((child) => child !== merged_number)
+async function inspect_children(epic: EpicIssue, merged_number: number): Promise<Array<ChildRead>> {
+	const siblings: Array<ChildReference> = epic.children
+		.filter((child) => child !== merged_number)
+		.map((number) => ({ number }))
 
-	return await Promise.all(siblings.map(async (sibling) => await inspect_sibling(sibling)))
+	return await Promise.all(
+		[...siblings, ...epic.external_children].map(async (child) => await inspect_child(child)),
+	)
 }
 
 // `pnpm josh epic --ordered` and `--add` record the declared chain themselves, through the REST
@@ -165,9 +177,8 @@ const CASCADE_DEPTH_NOTE = `⚠️  Epic auto-close cascade reached its ${String
 
 // **An unreadable comment listing does not stop the close.** It is announced and closed exactly as
 // it was before the duplicate check existed, because refusing here would strand the epic: nothing
-// re-triggers the auto-close once every child is closed — `resolve_and_close` only evaluates epics
-// holding the issue that just merged, and that merge has already happened. One rate-limited read
-// would leave a finished epic open until somebody noticed.
+// re-triggers the auto-close until some later child close sweeps the open epics, and that close may
+// never come. One rate-limited read would leave a finished epic open until somebody noticed.
 //
 // The direction is chosen on what each mistake costs, and they are not symmetric. Announcing twice
 // costs one redundant comment and nothing else, because the epic *closes* — which is what ends a loop
@@ -209,38 +220,26 @@ async function close_epic(epic: EpicIssue): Promise<boolean> {
 	return await close_epic_with(epic_number, comment)
 }
 
-// The cross-repository children's states, and whether every one of them could be read. An epic with
-// a child whose state is unknown keeps the old handling — left open for manual closing.
-async function inspect_external_children(
-	epic: EpicIssue,
-): Promise<{ states: Array<SiblingState>; is_complete: boolean }> {
-	if (epic.external_children.length === 0) return { states: [], is_complete: true }
-	const results = await Promise.all(
-		epic.external_children.map(async (child) => await inspect_external(child)),
-	)
+// The manual-close request is made only when every child that was read is closed: while one is still
+// open the batch is unfinished anyway, and asking for a manual close would invite closing it early.
+function warn_when_unread_blocks_close(epic: EpicIssue, states: ReadonlyArray<ChildRead>): void {
+	if (states.some((state) => state.is_readable && !state.is_closed)) return
 
-	return {
-		states: results.map((result) => ({
-			is_closed: result.is_closed,
-			has_blocked_by: result.has_blocked_by,
-		})),
-		is_complete: results.every((result) => result.is_readable),
-	}
+	console.info(
+		`⚠️  Epic ${session_cite.issue(epic.number)} has a child whose state could not be read; ${CLOSE_MANUALLY}`,
+	)
 }
 
+// An epic with a child whose state is unknown is left open for manual closing, and says so.
 async function close_epic_when_complete(epic: EpicIssue, merged_number: number): Promise<boolean> {
-	const external = await inspect_external_children(epic)
+	const states = await inspect_children(epic, merged_number)
 
-	if (!external.is_complete) {
-		console.info(
-			`ℹ️  Epic ${session_cite.issue(epic.number)} has a child in another repository whose state could not be read; ${CLOSE_MANUALLY}`,
-		)
+	if (states.some((state) => !state.is_readable)) {
+		warn_when_unread_blocks_close(epic, states)
 
 		return false
 	}
 
-	const states = [...(await inspect_siblings(epic, merged_number)), ...external.states]
-
 	warn_when_order_unrecorded(epic, states)
 
 	if (states.some((state) => !state.is_closed)) return false
@@ -315,22 +314,74 @@ async function close_next_level(
 	return next
 }
 
-// Breadth-first up the nesting: level 0 closes the epics holding the merged issue, and each closed
-// epic becomes the next level's completed child, so a fully-finished parent closes in the same pass.
-async function cascade_close(
+// Breadth-first up the nesting: each closed epic becomes the next level's completed child, so a
+// fully-finished parent closes in the same pass. `false` when the depth cap stopped the walk.
+async function cascade_from(
 	open_epics: ReadonlyArray<EpicIssue>,
-	merged_number: number,
-): Promise<void> {
-	const evaluated = new Set<number>()
-	let frontier: ReadonlyArray<number> = [merged_number]
+	start: ReadonlyArray<number>,
+	evaluated: Set<number>,
+): Promise<boolean> {
+	let frontier = start
 
 	for (let depth = 0; depth < MAX_CASCADE_DEPTH; depth++) {
-		if (frontier.length === 0) return
+		if (frontier.length === 0) return true
 		// eslint-disable-next-line no-await-in-loop -- the cascade closes one level before reading the next
 		frontier = await close_next_level(open_epics, frontier, evaluated)
 	}
 
 	if (frontier.length > 0) console.info(CASCADE_DEPTH_NOTE)
+
+	return frontier.length === 0
+}
+
+// An epic listing no child has nothing to be complete: with no state to read, the completion check
+// would close it — a prose epic, or one whose task list is not written yet.
+function tracks_children(epic: EpicIssue): boolean {
+	return epic.children.length + epic.external_children.length > 0
+}
+
+// Every open epic the cascade did not reach, closed when each child is: an epic whose last child
+// closed outside every josh path — an `already-done` child `run:merge` parked and a person closed by
+// hand (#4564) — is found by the next close of any child. An epic is marked evaluated only once it
+// closes, so a parent read before its child epic closed here is evaluated again by that cascade.
+//
+// A reopened epic is left out: a person reopening a finished epic has said it is not done, and only
+// a close of one of its own children — the cascade above — may close it again.
+function is_sweep_target(epic: EpicIssue, evaluated: ReadonlySet<number>): boolean {
+	return !evaluated.has(epic.number) && !epic.is_reopened && tracks_children(epic)
+}
+
+async function sweep_unreached(
+	open_epics: ReadonlyArray<EpicIssue>,
+	merged_number: number,
+	evaluated: Set<number>,
+): Promise<Array<number>> {
+	const closed: Array<number> = []
+	const unreached = open_epics.filter((epic) => is_sweep_target(epic, evaluated))
+
+	for (const epic of unreached) {
+		// eslint-disable-next-line no-await-in-loop -- a closed epic joins the evaluated set the cascade reads
+		if (await close_epic_isolated(epic, merged_number)) closed.push(epic.number)
+	}
+
+	for (const number of closed) evaluated.add(number)
+
+	return closed
+}
+
+// Level 0 closes the epics holding the merged issue; the sweep then closes any other finished epic.
+// A cascade stopped at the depth cap asks for a manual close, so the sweep does not run past it.
+async function cascade_close(
+	open_epics: ReadonlyArray<EpicIssue>,
+	merged_number: number,
+): Promise<void> {
+	const evaluated = new Set<number>()
+
+	if (!(await cascade_from(open_epics, [merged_number], evaluated))) return
+
+	const swept = await sweep_unreached(open_epics, merged_number, evaluated)
+
+	await cascade_from(open_epics, swept, evaluated)
 }
 
 const UNREADABLE_EPIC_LIST_MESSAGE =
@@ -363,9 +414,15 @@ async function resolve_and_close_safely(merged_number: number): Promise<void> {
 /**
  * Close every open epic whose task list is fully complete once `issue_number` closed.
  *
- * Requires `is_merged`: the linked Issue is treated as closed without being queried, which only
- * holds once the PR actually merged. On a `--no-merge` run that Issue is still open, so skipping
- * this guard would close an epic whose batch is not finished.
+ * **The one entry every child close goes through** (#4560): `followup` after its merge,
+ * `josh issue:measured` after its own close, and `run:merge` for every child it counts as merged —
+ * which also catches a merge GitHub left OPEN. Running it
+ * twice for one child is harmless: a closed epic is no longer in the open listing. Every other open
+ * epic is swept too, so one whose last child closed outside these paths closes here (#4564).
+ *
+ * Requires `is_merged` — the child is known closed: the linked Issue is treated as closed without
+ * being queried. On a `--no-merge` run that Issue is still open, so skipping this guard would close
+ * an epic whose batch is not finished.
  */
 async function close_completed_epics(input: {
 	issue_number: string | undefined

package/scripts/epic/epic-cross-repo.ts

@@ -2,6 +2,7 @@ import { repo_map_logic } from '#scripts/discovery/repo-map-logic'
 import { repo_origin } from '#scripts/discovery/repo-origin'
 import { git_gh_api_path } from '#scripts/gh/git-gh-api-path'
 import { git_gh_exec } from '#scripts/gh/git-gh-exec'
+import { json_value } from '#scripts/lib/json-value'
 import { GH_API_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { propagate_publish } from '#scripts/propagate/propagate-publish'
 import { derive_versions_endpoint } from '#scripts/version/version-command-config'
@@ -209,14 +210,10 @@ function to_answer(repo: string, fields: ManifestFields): ManifestAnswer {
 }
 
 function to_manifest(repo: string, stdout: string): ManifestAnswer {
-	try {
-		const parsed: unknown = JSON.parse(stdout.trim())
-		if (typeof parsed !== 'object' || parsed === null) return { kind: 'unreadable' }
+	const parsed = json_value.parse_or_undefined(stdout.trim())
+	if (typeof parsed !== 'object' || parsed === null) return { kind: 'unreadable' }
 
-		return to_answer(repo, parsed)
-	} catch {
-		return { kind: 'unreadable' }
-	}
+	return to_answer(repo, parsed)
 }
 
 // Why the read failed, asked only when it did. The status line is the protocol rather than prose, so

package/scripts/epic/epic-decide.ts

@@ -0,0 +1,119 @@
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { NEEDS_DECISION_LABEL } from '#scripts/issue/issue-labels'
+import { issue_read } from '#scripts/issue/issue-read'
+import { session_cite } from '#scripts/issue/session-cite'
+import { epic_decision } from './epic-decision'
+import { epic_parse } from './epic-parse'
+import { epic_read } from './epic-read'
+import type { EpicSubject } from './epic-validate'
+
+// `josh epic --decide <E> <N...> --decision-file <path|->` — record a decision about children the epic
+// already tracks: the epic's `## Decisions` entry, a comment on each child, and each child's
+// `needs-decision` label removed. The text is the caller's; placing it is this command's.
+//
+// **A rerun writes nothing twice.** The entry and each comment are looked for before they are
+// written, so a run that stopped half way is finished by running it again.
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+
+interface DecideInput {
+	epic_number: number
+	children: ReadonlyArray<number>
+	decision: string
+}
+
+function format_list(numbers: ReadonlyArray<number>): string {
+	return numbers.map((issue_number) => session_cite.issue(issue_number)).join(', ')
+}
+
+// A child the epic does not track is refused before anything is written: placing it is `--add`'s,
+// which records the same decision in the same call.
+function untracked_error(epic_number: number, untracked: ReadonlyArray<number>): string {
+	return `${format_list(untracked)} not tracked by ${session_cite.issue(epic_number)}; place it with \`pnpm josh epic --add ${String(epic_number)} <N> --decision-file <path>\`. Nothing was written.`
+}
+
+// The epic the decision goes to, or why nothing is written: a record `append_decision` would refuse
+// (checked before any read), an unreadable epic, or a child it does not track.
+async function read_decision_target(input: DecideInput): Promise<EpicSubject | { error: string }> {
+	const record_error = epic_decision.find_decision_error(input.decision)
+	if (record_error !== undefined) return { error: record_error }
+	const subject = await epic_read.read_subject(input.epic_number)
+
+	if (subject === undefined) {
+		return { error: `Could not read issue ${session_cite.issue(input.epic_number)}.` }
+	}
+
+	const tracked = epic_parse.parse_task_list_issue_numbers(subject.body)
+	const untracked = input.children.filter((child) => !tracked.includes(child))
+
+	return untracked.length === 0 ? subject : { error: untracked_error(input.epic_number, untracked) }
+}
+
+async function record_on_epic(subject: EpicSubject, decision: string): Promise<string> {
+	const epic = session_cite.issue(subject.number)
+
+	if (epic_decision.has_decision(subject.body, decision)) {
+		return `📝 ${epic} already records this decision.`
+	}
+
+	const body = epic_decision.append_decision(subject.body ?? '', decision)
+
+	await git_gh_command.issue_edit_body(String(subject.number), body)
+
+	return `📝 Decision recorded in ${epic}'s \`## Decisions\`.`
+}
+
+// `undefined` when the comments could not be read: posting then risks the duplicate this exists to
+// prevent, so the child is reported as not recorded and a rerun finishes it.
+async function has_comment(child: number, decision: string): Promise<boolean | undefined> {
+	const comments = await issue_read.parse_comments(
+		await git_gh_command.issue_list_comments(String(child)),
+	)
+
+	return comments?.some((comment) => comment.body.trim() === decision.trim())
+}
+
+// The label goes only once the child carries the record, so a failed comment leaves it parked.
+async function record_on_child(child: number, decision: string): Promise<boolean> {
+	const has_record = await has_comment(child, decision)
+	if (has_record === undefined) return false
+	const is_commented =
+		has_record || (await git_gh_command.issue_try_comment(String(child), decision))
+	if (!is_commented) return false
+
+	return await git_gh_command.issue_clear_label(String(child), NEEDS_DECISION_LABEL)
+}
+
+function format_child_report(total: number, failures: number): string {
+	if (failures === 0) return epic_decision.format_decision_report({ total, failures })
+
+	return `⚠️  ${String(failures)} of ${String(total)} child issue(s) could not be given the comment or lose \`${NEEDS_DECISION_LABEL}\`; rerun the same command — nothing is written twice.`
+}
+
+async function decide(input: DecideInput): Promise<number> {
+	const epic = await read_decision_target(input)
+
+	if ('error' in epic) {
+		console.error(`✖ ${epic.error}`)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	console.info(await record_on_epic(epic, input.decision))
+	const recorded = await Promise.all(
+		input.children.map(async (child) => await record_on_child(child, input.decision)),
+	)
+	const failures = recorded.filter((is_recorded) => !is_recorded).length
+
+	console.info(format_child_report(input.children.length, failures))
+
+	return failures === 0 ? SUCCESS_EXIT_CODE : FAILURE_EXIT_CODE
+}
+
+const epic_decide = {
+	decide,
+}
+
+export { epic_decide }
+export type { DecideInput }

package/scripts/epic/epic-decision.ts

@@ -153,8 +153,17 @@ function read_recorded_reasons(body: string | undefined): string {
 	].join('\n')
 }
 
+// Whether `## Decisions` already carries this record, compared as `append_decision` writes it — so a
+// rerun of `epic --decide` after a partial failure appends nothing a second time.
+function has_decision(body: string | undefined, record: string): boolean {
+	if (body === undefined) return false
+
+	return read_section(body, DECISIONS_HEADING_PATTERN).includes(record.trimEnd())
+}
+
 const epic_decision = {
 	append_decision,
+	has_decision,
 	append_replacements,
 	read_recorded_reasons,
 	find_decision_error,