@joshuafolkken/kit 1.1240.0 → 1.1373.0

package/scripts/gh/git-gh-failure.ts

@@ -1,12 +1,10 @@
 import { parse_json } from '#scripts/git/parse-json-array'
 import { z } from 'zod'
 
-// Why one `gh api` request failed, taken from **that request** rather than from a later probe
-// (joshuafolkken/kit#1690).
+// Why one `gh api` request failed, taken from **that request** rather than from a later probe.
 //
-// joshuafolkken/kit#957 asked the same question by issuing a second request — `exec_gh_api_status`
-// against the same path — and joshuafolkken/kit#1663 asked it again with a reachability probe fired
-// after the answer was otherwise final. Both are inferences about a request that is already over: a
+// A second request — `exec_gh_api_status` against the same path, or a reachability probe fired
+// after the answer is otherwise final — is only an inference about a request that is already over: a
 // connection that dropped for three hundred milliseconds fails the read and answers the probe
 // `reachable`, so the failure keeps the meaning the probe gave it and not the one it had.
 //
@@ -14,7 +12,7 @@ import { z } from 'zod'
 // `gh api` writes the **response body** to stdout, and GitHub's REST error document carries its own
 // status — `{"message":"Not Found","documentation_url":…,"status":"404"}`. A request that never
 // reached GitHub has no response body at all, so stdout is empty. That is the whole classification,
-// and neither half reads gh's stderr prose, which is what joshuafolkken/kit#1024 refused to key on.
+// and neither half reads gh's stderr prose, which is wording rather than protocol.
 
 // GitHub's REST error document. Only the status is read: `message` and `documentation_url` are prose
 // for a person, and every other field varies by endpoint.
@@ -41,8 +39,7 @@ interface GhFailure {
 	// for a related resource, reached only because the first answered. Such a request fails about
 	// itself, so its 404 says nothing about whether the subject exists: an issue read whose blocker
 	// relations then 404 on a host without that endpoint is a readable issue, not a missing one. Only
-	// the caller knows which of its requests was which, so it is the caller that sets this
-	// (joshuafolkken/kit#1690).
+	// the caller knows which of its requests was which, so it is the caller that sets this.
 	is_followup?: boolean
 }
 
@@ -62,7 +59,7 @@ function has_gh_failure(error: unknown): error is Error & { gh_failure: GhFailur
 // nothing in it says what the status was, and guessing one would be the inference this module
 // exists to remove.
 function parse_response_status(stdout: string): number | undefined {
-	const document = parse_json.parse_json_object_safe(stdout, error_document_schema)
+	const document = parse_json.parse_json_object_or_undefined(stdout, error_document_schema)
 	if (document?.status === undefined) return undefined
 	const status = Number(document.status)
 

package/scripts/gh/git-gh-helpers.ts

@@ -4,7 +4,7 @@ import { has_stderr_field } from './git-gh-exec'
 // string itself, so the value arrives raw and there is nothing to unquote — this used to strip a
 // leading and trailing `"` anyway, which ate real characters from any answer that legitimately
 // carried them. A title of `"queue" should stop at the first failure` reached Telegram as
-// `queue" should stop at the first failure` (joshuafolkken/kit#993). Trimming and the empty answer
+// `queue" should stop at the first failure`. Trimming and the empty answer
 // are the whole contract.
 function parse_pr_state_string(result: string): string | undefined {
 	const trimmed = result.trim()

package/scripts/gh/git-gh-issue-list.ts

@@ -12,13 +12,12 @@ import {
 // Listing issues through REST, in the JSON shape `gh issue list --json <fields>` answered with.
 //
 // `gh issue list` goes through GraphQL, which a cloud session is answered 403 for; the REST listing
-// is served normally (joshuafolkken/kit#1022). The callers differ only in filter and fields, so
+// is served normally. The callers differ only in filter and fields, so
 // the request, the paging and the mapping are decided once here and every caller downstream keeps
-// reading the field names it already reads (joshuafolkken/kit#1025).
+// reading the field names it already reads.
 //
-// It was `issue_list_open` until joshuafolkken/kit#1679, when the duplicate scan needed the issue
-// that closed an hour ago and `state` became a parameter. The name went with the behavior rather
-// than being left to describe six of seven callers.
+// `state` is a parameter because the duplicate scan needs the issue that closed an hour ago, and the
+// name describes that behavior rather than the open-only listing most callers ask for.
 //
 // The field mapping itself is `git-gh-issue-rest.ts`, the same one the single-issue read goes
 // through: a listing row and a read response are the same object, so a second copy of the state
@@ -38,7 +37,7 @@ const LISTING_DIRECTION = 'direction=desc'
 
 // `state` and `sort` are parameters rather than constants because the duplicate scan has to see the
 // issue that closed an hour ago: the work most likely to be filed twice is the work that just
-// finished, and a listing fixed at `state=open` cannot show it (joshuafolkken/kit#1679). Ordering a
+// finished, and a listing fixed at `state=open` cannot show it. Ordering a
 // closed listing by `created` would rank it by when each issue was *filed*, which says nothing about
 // when it closed — so the sort travels with the state rather than being fixed alongside it.
 //
@@ -77,7 +76,7 @@ function listing_path(request: IssueListRequest, page: number): string {
 	return `${git_gh_api_path.issues_api_path(request.repo)}?${listing_query(request)}${label}${paging}`
 }
 
-// `--search "<term> in:body"` matched tokens, so `#858` never matched inside `#8580`. A bare
+// `--search "<term> in:body"` matches tokens, so `#858` never matches inside `#8580`. A bare
 // substring test does, and those false positives fill the caller's `limit` newest-first — crowding
 // out an older genuine match, which `epic:audit` would then never report. The term is always
 // `#<number>`, whose `#` anchors the left side, so only a trailing digit has to be refused.
@@ -126,22 +125,19 @@ async function fetch_page(
 
 // The ceiling on how far *any* listing pages. Without it a request pages until the backlog runs
 // out: the body search's matches are normally zero, so "stop once `limit` rows are selected" never
-// fires for it (joshuafolkken/kit#1033), and the other five reach `limit` only after the client-side
+// fires for it, and the other five reach `limit` only after the client-side
 // pull-request exclusion has discarded whatever the endpoint served alongside the issues — which in
-// a repository with hundreds of open pull requests is the whole backlog again
-// (joshuafolkken/kit#1067).
+// a repository with hundreds of open pull requests is the whole backlog again.
 //
 // Five pages bounds every listing at five requests, and five hundred rows is comfortably above what
 // each caller asks for: the widest is `epic:bundle`'s two hundred, which the ceiling only cuts short
 // once more than three in five of the newest five hundred open items are pull requests. A repository
 // big enough to reach it is *told* rather than handed a shorter answer.
 //
-// **It applies to every listing only because the flag now reaches every caller.** Until
-// joshuafolkken/kit#1067 `issue_list` discarded `is_capped`, so bounding a listing whose caller
-// could not read the flag would have shortened that listing's answer in silence — the defect the
-// bound exists to prevent, introduced by the fix for it. Threading the flag out came first for that
-// reason, and the two must never be separated again: a ceiling is only ever as safe as the caller's
-// ability to say it was reached.
+// **It applies to every listing only because the flag reaches every caller.** Bounding a listing
+// whose caller cannot read `is_capped` would shorten that listing's answer in silence — the defect
+// the bound exists to prevent. So the two must never be separated: a ceiling is only ever as safe as
+// the caller's ability to say it was reached.
 const MAX_PAGES = 5
 // The ceiling in issues, which is how the callers that report the gap phrase it.
 const MAX_SCANNED = MAX_PAGES * PER_PAGE
@@ -199,7 +195,7 @@ async function fetch_selected(request: IssueListRequest): Promise<SelectedRows>
 // issue GitHub itself reports as unblocked costs no request. A backlog with no declared blockers
 // therefore costs exactly what `gh` cost — one listing — rather than one request per row.
 //
-// Bounded rather than sequential (joshuafolkken/kit#3103): the pass was paced one request at a time,
+// Bounded rather than sequential: the pass was paced one request at a time,
 // which made every `backlog:plan` wait about 0.7 s per opted-in issue declaring a blocker. The width
 // is the one `epic:bundle` already reads the same endpoint at, so the burst stays bounded while a
 // rate-limited read still fails the whole listing rather than a row (`bounded-pool.ts`).
@@ -218,7 +214,7 @@ async function read_relations(
 
 // The listing, plus what it could not cover. `json` is `undefined` — never `'[]'` — when the listing
 // could not be read: `epic:next`'s per-repository exclusion reads this answer, and "nothing is
-// running" is what *starts* a second run in the same checkout (joshuafolkken/kit#925).
+// running" is what *starts* a second run in the same checkout.
 //
 // `is_capped` is `false` on that failure path, and says nothing there: an unreadable listing is
 // already fully described by `json`, and a caller reading a truncation flag off it would be reading
@@ -246,7 +242,7 @@ async function issue_list(request: IssueListRequest): Promise<IssueListOutcome>
 	}
 }
 
-// The flag-discarding second entry point is gone (joshuafolkken/kit#1067). It answered
+// The flag-discarding second entry point is gone. It answered
 // `string | undefined` for the five callers that could not reach the page ceiling, and once the
 // ceiling applies to all six there is no such caller left: a wrapper that dropped `is_capped` would
 // be the one way back to a silently shortened answer, so it is removed rather than left for someone

package/scripts/gh/git-gh-issue-read.ts

@@ -13,26 +13,22 @@ import { gh_reachability } from './git-gh-reachability'
 
 // Reading one issue. Split out of `git-gh-issue.ts`, which had grown past the file-length limit
 // while holding both the reads and the writes; the reads are what every epic command goes through,
-// and telling a number that resolves to nothing from a read that failed belongs with them
-// (joshuafolkken/kit#957).
+// and telling a number that resolves to nothing from a read that failed belongs with them.
 
 // The blocker relations, which REST serves from their own endpoint rather than inside the issue.
 // `gh issue view --json blockedBy` answered them in the same response because GraphQL selects them
-// as a connection; REST needs a second request (joshuafolkken/kit#1024).
+// as a connection; REST needs a second request.
 //
 // One page of a hundred — `FULL_PAGE_QUERY`, the same one every other listing here asks for — where
 // GraphQL asked for `blockedBy(first:50)`, so `nodes` is at least as complete as it was, while
 // `totalCount` comes from the issue's own dependency summary and stays exact whatever the page
-// holds. The endpoint itself is named in `git-gh-api-path.ts`, which the two writes address as well
-// (joshuafolkken/kit#1026).
+// holds. The endpoint itself is named in `git-gh-api-path.ts`, which the two writes address as well.
 //
-// joshuafolkken/kit#1113 split this out for the one caller that may not consult the summary the
-// wrapper below trusts: the summary is GitHub's own count and it can disagree with the listing it
-// counts. Measured on joshuafolkken/kit#1111, whose `issue_dependencies_summary` read
-// `total_blocked_by: 0` while this endpoint returned `#1106` — and re-POSTing that relation was
-// refused with `Target issue has already been taken`, so the relation was real and only the counter
-// was wrong. `epic:next` then called a graph that agreed with itself contradictory and exited 1,
-// which stops an unattended run at its first step with nothing to fix.
+// Split out for the one caller that may not consult the summary the wrapper below trusts: the
+// summary is GitHub's own count and it can disagree with the listing it counts — an
+// `issue_dependencies_summary` can read `total_blocked_by: 0` while this endpoint returns a real
+// relation. Trusting the counter there makes `epic:next` call a graph that agrees with itself
+// contradictory and exit 1, which stops an unattended run at its first step with nothing to fix.
 async function read_blocked_by_listing(
 	issue_number: string,
 	repo?: string,
@@ -48,22 +44,20 @@ async function read_blocked_by_listing(
 // The same relations, with the request skipped when the issue's own summary says the count is zero.
 // That skip is the common case and the one that matters for cost: `epic:bundle` reads relations for
 // the whole open backlog, up to two hundred issues, and every one of those reads names `blockedBy`.
-// Without it the pass would be four hundred requests where `gh` made two hundred — which is why
-// joshuafolkken/kit#1113 left it in place and gave the rare path its own entry point above rather
-// than making every read pay for it.
+// Without it the pass would be four hundred requests instead of two hundred — which is why the rare
+// path has its own entry point above rather than making every read pay for it.
 //
 // A pull request is skipped ahead of that, structurally rather than on a count. It carries no
 // `issue_dependencies_summary` at all, and an absent summary is deliberately not read as a zero — so
 // the numeric skip cannot fire for one, and the endpoint was asked every time. GitHub answers an
 // empty array today, but a 404 there would fail the whole read and `epic:bundle` would report the
-// reference as `unreadable` **before** the `/pull/` check that drops it (joshuafolkken/kit#947) ever
-// ran. The guard rested on API behavior nobody controls; this makes it a fact about pull requests
-// (joshuafolkken/kit#1066).
+// reference as `unreadable` **before** the `/pull/` check that drops it ever
+// ran. The guard rested on API behavior nobody controls; this makes it a fact about pull requests.
 //
 // Exported because the *listings* need exactly this, and for exactly this reason: a listing response
 // carries every row's `issue_dependencies_summary` but no `blockedBy`, so the pickup that asks for
 // the field pays one request per row that declares a blocker and nothing for the rest. A second copy
-// beside the listing requests is the clone `CLAUDE.md` prohibits (joshuafolkken/kit#1025).
+// beside the listing requests is the clone `CLAUDE.md` prohibits.
 async function read_blocked_by(
 	issue_number: string,
 	rest: RestIssue,
@@ -88,7 +82,7 @@ function mark_followup(error: unknown): unknown {
 	return gh_failure.attach(error, { ...failure, is_followup: true })
 }
 
-// The relations, marked as the follow-up request they are (joshuafolkken/kit#1690).
+// The relations, marked as the follow-up request they are.
 //
 // **One read, two requests, one classifier.** The relations endpoint is reached only after the issue
 // itself came back, so by then the number has resolved — and yet the caller catches a single error
@@ -109,8 +103,7 @@ async function read_relations(
 }
 
 // One issue through REST, answered in the field names `gh issue view --json` used. Every read below
-// goes through it, so the request, the field mapping and the blocker relations are decided once
-// (joshuafolkken/kit#1024).
+// goes through it, so the request, the field mapping and the blocker relations are decided once.
 //
 // The blocker request is made **only** when `blockedBy` was asked for — the title, body and
 // labels-and-body reads never name it — and, when it was, only when the issue itself reports a
@@ -136,10 +129,10 @@ async function read_issue_fields(
 // another repository's number quoted in prose — which is an answer rather than a gap. `unreadable`
 // is a gap: a rate limit, expired auth, a dropped connection. Folding the two together had one
 // non-existent number reported as something the command had failed to read, which stops an
-// unattended run for a reference that never existed (joshuafolkken/kit#957).
+// unattended run for a reference that never existed.
 //
-// **`reason` splits the gap into the three answers a caller acts on differently**
-// (joshuafolkken/kit#1690). `unreachable` is retryable — nothing answered, or GitHub answered 429 or
+// **`reason` splits the gap into the three answers a caller acts on differently**.
+// `unreachable` is retryable — nothing answered, or GitHub answered 429 or
 // 5xx — so the same request a moment later can succeed and an unattended run should ask again rather
 // than report the backlog empty. `rejected` is an answer that will not change on its own: expired
 // auth, an org policy, a 403. `malformed` is a response that arrived and could not be used, which is
@@ -161,19 +154,17 @@ type FieldRead = IssueReadFailure | { kind: 'read'; text: string | undefined }
 // not there.
 const NOT_FOUND_STATUS = 404
 
-// Why the read failed, read off **the failed request** rather than off a second one
-// (joshuafolkken/kit#1690).
+// Why the read failed, read off **the failed request** rather than off a second one.
 //
-// joshuafolkken/kit#957 answered this by probing the same path again for its status, and
-// joshuafolkken/kit#1024 kept the probe because gh surfaces a failure as stderr text and classifying
-// by that wording is prose-matching. Both premises held; the conclusion did not. `gh api` writes the
-// **response body** to stdout, and GitHub's own error document carries the status there — so the
-// status was on the failed request all along, and `git-gh-failure.ts` takes it from there.
+// Classifying by gh's stderr wording would be prose-matching, but no second request is needed:
+// `gh api` writes the **response body** to stdout, and GitHub's own error document carries the
+// status there — so the status is on the failed request itself, and `git-gh-failure.ts` takes it
+// from there.
 //
 // **A second request cannot answer about the first.** A connection that dropped for a moment fails
-// the read and answers the probe `reachable`, and the read then keeps the meaning the probe gave it.
-// Removing the probe removes that, and removes the extra request with it: the classification is now
-// free, so `epic:bundle`'s bounded lookup no longer trades accuracy against a rate limit it would
+// the read and answers a probe `reachable`, and the read would then keep the meaning the probe gave
+// it. Reading the failed request avoids that and the extra request with it: the classification is
+// free, so `epic:bundle`'s bounded lookup does not trade accuracy against a rate limit it would
 // deepen.
 //
 // An error carrying no classification at all did not come from the request: `parse_rest_issue` and
@@ -191,7 +182,7 @@ function to_read_failure(error: unknown): IssueReadFailure {
 
 	if (failure === undefined) return { kind: 'unreadable', reason: 'malformed', status: undefined }
 	// Only the request that resolves the number can report it as resolving to nothing. A follow-up
-	// request's own 404 is about that endpoint (joshuafolkken/kit#1690).
+	// request's own 404 is about that endpoint.
 	if (is_number_unresolved(failure)) return { kind: 'missing' }
 
 	return {
@@ -220,8 +211,7 @@ async function issue_view_json_classified(
 //
 // The unwrapped `string | undefined` below is this same read with the reason dropped, rather than a
 // second read that never had one: a caller that only wants the text keeps its signature, and one
-// that has to tell "the body is empty" from "the body could not be read" now can
-// (joshuafolkken/kit#1690).
+// that has to tell "the body is empty" from "the body could not be read" now can.
 async function issue_view_field_classified(
 	issue_number: string,
 	field: string,
@@ -247,12 +237,10 @@ async function issue_view_field(
 	return read.kind === 'read' ? read.text : undefined
 }
 
-// An extracted string arrives raw — nothing quotes it — and an empty answer is not a title
-// (joshuafolkken/kit#993).
+// An extracted string arrives raw — nothing quotes it — and an empty answer is not a title.
 //
 // `repo` reads the title of an issue in another repository — what `josh notify` needs when the
-// `--issue-url` it was given points outside the repository the session runs in
-// (joshuafolkken/kit#903).
+// `--issue-url` it was given points outside the repository the session runs in.
 async function issue_get_title(issue_number: string, repo?: string): Promise<string | undefined> {
 	const result = await issue_view_field(issue_number, 'title', repo)
 
@@ -265,15 +253,14 @@ async function issue_get_body(issue_number: string, repo?: string): Promise<stri
 
 // The body, plus why it produced nothing when it did. An epic's body is the one read whose absence
 // is indistinguishable from a legitimate answer — an epic with no task list and an epic nobody could
-// read both parse to zero children — so the caller that builds the dependency graph takes this one
-// (joshuafolkken/kit#1690).
+// read both parse to zero children — so the caller that builds the dependency graph takes this one.
 async function issue_get_body_classified(issue_number: string, repo?: string): Promise<FieldRead> {
 	return await issue_view_field_classified(issue_number, 'body', repo)
 }
 
 // A JSON view of one issue, for every caller that wants several fields at once. Callers differ only
 // in which fields they ask for, and a helper per field list is how four near-identical functions
-// accumulated (joshuafolkken/kit#862).
+// accumulated.
 //
 // The field list is still spelled the way `gh issue view --json` spelled it, and so is the answer:
 // the translation to and from REST is `git-gh-issue-rest.ts`, so no caller downstream changed.
@@ -289,11 +276,11 @@ async function issue_view_json(
 
 // State, labels and dependency relations in one read: the epic auto-close needs state and relations
 // per child, `epic:next` needs the labels too, and splitting them would multiply the API calls for
-// no gain (joshuafolkken/kit#860).
+// no gain.
 //
 // `repo` reads a child in another repository. Cross-repository children are read this way rather
 // than from a local checkout: their state is a GitHub fact, and requiring a clone to learn it is
-// what kept the auto-close from ever running on such an epic (joshuafolkken/kit#864).
+// what kept the auto-close from ever running on such an epic.
 const STATE_AND_RELATIONS_FIELDS = 'number,state,labels,blockedBy'
 
 async function issue_get_state_and_relations(
@@ -304,8 +291,7 @@ async function issue_get_state_and_relations(
 }
 
 // The same read, plus why it produced nothing when it did. An epic's children are read this way, and
-// an unattended run has to tell a child it could not reach from one it may never reach
-// (joshuafolkken/kit#1690).
+// an unattended run has to tell a child it could not reach from one it may never reach.
 async function issue_get_state_and_relations_classified(
 	issue_number: string,
 	repo?: string,
@@ -325,8 +311,7 @@ function is_unreachable_read(failure: IssueReadFailure): boolean {
 //
 // `epic:bundle` reads a referenced issue through the same call rather than adding a helper for its
 // own field list — it needs the body and the state, which is a subset of this one, and a helper per
-// field list is exactly how the four near-identical functions above accumulated
-// (joshuafolkken/kit#947).
+// field list is exactly how the four near-identical functions above accumulated.
 const PLAN_FIELDS = 'number,title,body,state,url,labels,blockedBy'
 
 async function issue_get_plan_fields(issue_number: string): Promise<string | undefined> {
@@ -336,12 +321,12 @@ async function issue_get_plan_fields(issue_number: string): Promise<string | und
 // The same fields, with a failed read told apart from a number that resolves to nothing.
 // `epic:bundle` reads a reference this way because the two answers belong in different places: a
 // missing number is neither a candidate nor a gap, while an unreadable one is reported so a verdict
-// is never quietly based on data that never arrived (joshuafolkken/kit#957).
+// is never quietly based on data that never arrived.
 async function issue_get_plan_fields_classified(issue_number: string): Promise<IssueRead> {
 	return await issue_view_json_classified(issue_number, PLAN_FIELDS)
 }
 
-// `state` rides along for `epic-add.ts`'s closed-epic refusal (joshuafolkken/kit#2337); every
+// `state` rides along for `epic-add.ts`'s closed-epic refusal; every
 // other caller reads only the labels and body and ignores it, so it costs no extra request.
 async function issue_get_labels_and_body(issue_number: string): Promise<string | undefined> {
 	return await issue_view_json(issue_number, 'number,state,labels,body')
@@ -349,8 +334,7 @@ async function issue_get_labels_and_body(issue_number: string): Promise<string |
 
 // The conversation comments of one issue, as REST serves them. `undefined` — never `'[]'` — when the
 // listing could not be read: the one caller has to tell "this epic carries no closing comment" from
-// "nobody looked", because posting on the second answer is the duplicate it exists to prevent
-// (joshuafolkken/kit#1039).
+// "nobody looked", because posting on the second answer is the duplicate it exists to prevent.
 //
 // Paged, and for the same reason `pr_get_comments` is: REST answers 30 rows and an epic's
 // conversation outgrows that, while the comment being looked for is the **newest** one — so an
@@ -380,8 +364,7 @@ async function issue_list_comments(issue_number: string): Promise<string | undef
 // than read off `gh`'s stderr wording, because classifying by the message is prose-matching.
 //
 // **This one could read the failed request instead, and deliberately does not** — its caller reaches
-// it from a `catch`, where the error it holds already carries `gh_failure` since
-// joshuafolkken/kit#1690. What is asked here is not "why did that request fail" but "does this
+// it from a `catch`, where the error it holds already carries `gh_failure`. What is asked here is not "why did that request fail" but "does this
 // endpoint exist on this host", and the answer has to hold for a `read_blocked_by_listing` that
 // failed for some other reason entirely. Reusing the caught failure would fold the two questions
 // into one.
@@ -394,17 +377,17 @@ async function has_no_relations_endpoint(issue_number: string, repo?: string): P
 }
 
 // The blocker numbers of one issue, read from the relations listing rather than from the issue's own
-// summary count (joshuafolkken/kit#1113). Exposed on the command object so the callers that need the
+// summary count. Exposed on the command object so the callers that need the
 // uncounted answer reach it the way they reach every other read, and so a suite that already fakes
 // the command layer does not fall through to a real `gh api`.
 //
 // A 404 is answered as no relations rather than raised. `read_blocked_by` never reaches this
-// endpoint for a pull request — joshuafolkken/kit#1066 skips one structurally, since a PR carries no
+// endpoint for a pull request — it skips one structurally, since a PR carries no
 // `issue_dependencies_summary` to skip on — and this entry point has no issue payload to make that
 // judgement from. A PR pasted into an epic's task list would otherwise turn a read of an endpoint
 // that has nothing for it into a warning about a relation nobody lost. Every other failure still
 // raises: a rate limit is a gap, and the caller says so.
-// The same relations, each carrying the repository it lives in (joshuafolkken/kit#1126). A
+// The same relations, each carrying the repository it lives in. A
 // `blocked-by` relation may cross a repository, and a number alone cannot say which one it names —
 // issue numbers are unique per repository — so a caller that orders work has to keep the pair.
 //

package/scripts/gh/git-gh-issue-rest.ts

@@ -1,7 +1,7 @@
 import { blocking_issue_schema } from '#scripts/git/git-schemas'
 import {
 	parse_json_array_or_undefined,
-	parse_json_object_safe,
+	parse_json_object_or_undefined,
 } from '#scripts/git/parse-json-array'
 import type { IssueReference } from '#scripts/issue/issue-reference'
 import { z } from 'zod'
@@ -11,11 +11,10 @@ import { MERGED_STATE, to_gh_state } from './git-gh-rest-state'
 // `gh issue view --json <fields>` used to answer with.
 //
 // `gh issue view` goes through GraphQL, which a cloud session is answered 403 for while the REST
-// endpoint is served normally (joshuafolkken/kit#1022). The reads in `git-gh-issue-read.ts` are what
+// endpoint is served normally. The reads in `git-gh-issue-read.ts` are what
 // every epic command goes through, so they move to REST — and every caller downstream keeps reading
 // the field names it already reads. The mapping lives here rather than beside the requests because
-// it is pure: given the two responses, it decides the answer with nothing else to know
-// (joshuafolkken/kit#1024).
+// it is pure: given the two responses, it decides the answer with nothing else to know.
 
 // Only the fields the mapping itself reads are named; every other key passes through untouched,
 // which is what lets a caller ask for a field this file has never heard of.
@@ -52,7 +51,7 @@ const BLOCKED_BY_FIELD = 'blockedBy'
 // purpose: `blockedBy` is a connection `gh` served inside the issue, while this is the exact count
 // GitHub already puts in the listing's own `issue_dependencies_summary`. A caller that asks for it
 // learns whether an issue has blockers **without** the per-issue request that reading `blockedBy`
-// costs — which is what lets `epic:bundle` stop re-reading every open issue (joshuafolkken/kit#1736).
+// costs — which is what lets `epic:bundle` stop re-reading every open issue.
 //
 // It is `undefined` rather than `0` where the summary is absent — a pull request, which this
 // endpoint serves as readily as an issue, carries none. Reading that as "no blockers" is the one
@@ -63,7 +62,7 @@ const BODY_FIELD = 'body'
 const FIELD_SEPARATOR = ','
 const EMPTY_BODY = ''
 
-// The two field names REST and `gh --json` disagree on. `url` is the one that bites: REST's `url` is
+// The field names REST and `gh --json` disagree on. `url` is the one that bites: REST's `url` is
 // the API endpoint, while `gh` answers the browser URL — and `epic_issue.is_pull_request` decides
 // from `/pull/` appearing in it, which the API endpoint never carries.
 //
@@ -71,6 +70,7 @@ const EMPTY_BODY = ''
 const REST_FIELD_NAMES = new Map<string, string>([
 	['url', 'html_url'],
 	['createdAt', 'created_at'],
+	['closedAt', 'closed_at'],
 ])
 
 const NOT_AN_ISSUE_MESSAGE = 'gh api answered something other than an issue object'
@@ -123,7 +123,7 @@ function to_gh_field_value(field: string, rest: RestIssue): unknown {
 // catch it into `undefined`, which is the same "the read failed" every other failure produces, while
 // a partial object would be reported as an issue whose fields are all missing.
 function parse_rest_issue(rest_json: string): RestIssue {
-	const parsed = parse_json_object_safe(rest_json, rest_issue_schema)
+	const parsed = parse_json_object_or_undefined(rest_json, rest_issue_schema)
 	if (parsed === undefined) throw new Error(NOT_AN_ISSUE_MESSAGE)
 
 	return parsed
@@ -131,8 +131,7 @@ function parse_rest_issue(rest_json: string): RestIssue {
 
 // `repos/{owner}/{repo}/issues` serves pull requests alongside issues; `gh issue list` never did,
 // and its six callers all read the answer as issues. The key is present on a pull request and
-// absent on an issue, which is the same signal `to_issue_state` already reads
-// (joshuafolkken/kit#1025).
+// absent on an issue, which is the same signal `to_issue_state` already reads.
 function is_pull_request(rest: RestIssue): boolean {
 	return rest.pull_request !== undefined && rest.pull_request !== null
 }
@@ -140,7 +139,7 @@ function is_pull_request(rest: RestIssue): boolean {
 // One page of the listing endpoint, whose elements are the same objects `parse_rest_issue` reads one
 // of. It throws for the reason that one does: a response that is not a listing — `gh` answering
 // `{"message":"API rate limit exceeded"}` — must not degrade into an empty listing, which every
-// caller here reads as "there is nothing" (joshuafolkken/kit#950).
+// caller here reads as "there is nothing".
 function parse_rest_issues(rest_json: string): Array<RestIssue> {
 	const parsed = parse_json_array_or_undefined(rest_json, rest_issue_schema)
 	if (parsed === undefined) throw new Error(NOT_AN_ISSUE_LISTING_MESSAGE)
@@ -151,7 +150,7 @@ function parse_rest_issues(rest_json: string): Array<RestIssue> {
 // The connection for an issue GitHub itself says has no blockers, answered without a request. `gh`
 // sent `blockedBy` inside the issue response, so a second request per issue would double
 // `epic:bundle`'s pass over the whole open backlog — and the issue's own summary settles the common
-// case, which is an issue with no blockers at all (joshuafolkken/kit#1024).
+// case, which is an issue with no blockers at all.
 function empty_blocked_by(): BlockedBy {
 	return { nodes: [], totalCount: 0 }
 }
@@ -160,7 +159,7 @@ function empty_blocked_by(): BlockedBy {
 //
 // A blocker relation may cross a repository, and the number alone cannot say which one it is: issue
 // numbers are unique per repository, so a blocker read bare resolves against the blocked child's own
-// repository and names a different issue there (joshuafolkken/kit#1126). Undefined when the field is
+// repository and names a different issue there. Undefined when the field is
 // absent or shaped otherwise; the caller then falls back to the repository it is reading in, which is
 // what an unqualified relation has always meant.
 function repo_of_url(repository_url: string | undefined = ''): string | undefined {
@@ -174,7 +173,7 @@ function repo_of_url(repository_url: string | undefined = ''): string | undefine
 //
 // A listing that will not parse throws instead of answering an empty connection. That direction is
 // the point: an empty `nodes` reads as "this child has no blockers", and `epic:next` would then hand
-// a dependent to an unattended run before its prerequisite (joshuafolkken/kit#1005).
+// a dependent to an unattended run before its prerequisite.
 function to_blocked_by(blockers_json: string, exact_total?: number): BlockedBy {
 	const parsed = parse_json_array_or_undefined(blockers_json, blocking_issue_schema)
 	if (parsed === undefined) throw new Error(NOT_A_BLOCKER_LISTING_MESSAGE)
@@ -209,8 +208,8 @@ function to_field_text(value: unknown): string {
 
 const CLOSED = 'CLOSED'
 
-// One blocker node as a reference, keeping the state the relation response carried
-// (joshuafolkken/kit#1943). Single-sourced here because the snapshot read and the candidate re-read
+// One blocker node as a reference, keeping the state the relation response carried.
+// Single-sourced here because the snapshot read and the candidate re-read
 // both unwrap the same node, and the state is omitted rather than guessed when REST did not send it.
 function reference_of_blocker(
 	node: z.infer<typeof blocking_issue_schema>,