@joshuafolkken/kit 1.1240.0 → 1.1370.0

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

@@ -1,23 +1,24 @@
+import { session_cite } from '#scripts/issue/session-cite'
 import { error_text } from '#scripts/lib/error-message'
 import { git_gh_api_path } from './git-gh-api-path'
 import { git_gh_exec, type GhApiRequest } from './git-gh-exec'
+import { gh_failure } from './git-gh-failure'
 
 // Writing issues and labels through REST, in the return-value contracts the `gh <noun> <verb>`
 // wrappers had.
 //
 // `gh issue edit` / `comment` / `create` / `close` and `gh label create` all go through GraphQL,
-// which a cloud session is answered 403 for while the REST endpoints are served normally
-// (joshuafolkken/kit#1022). Split out of `git-gh-issue.ts` rather than added to it: that file was
+// which a cloud session is answered 403 for while the REST endpoints are served normally.
+// Split out of `git-gh-issue.ts` rather than added to it: that file was
 // already at 215 of the 300 lines a file may hold, and the reads had been split out for the same
-// reason (joshuafolkken/kit#957, joshuafolkken/kit#1026).
+// reason.
 //
-// **Every path here was measured against the live API before it was written.**
-// joshuafolkken/kit#1022 deliberately measured only the reads, because a write has side effects, and
-// left the write side as candidates to confirm one at a time. They were confirmed on a pair of
-// throwaway issues, and one of them did not behave as its name suggests — see `read_issue_id`.
+// **Every path here is measured against the live API.** A write has side effects, so each one is
+// confirmed on throwaway issues, and one of them does not behave as its name suggests — see
+// `read_issue_id`.
 //
-// The bodies still travel over stdin: `exec_gh_api` hands `body` to gh as `--input -`, so multi-line
-// markdown depends on no shell quoting, exactly as `--body-file -` did before.
+// The bodies travel over stdin: `exec_gh_api` hands `body` to gh as `--input -`, so multi-line
+// markdown depends on no shell quoting.
 
 // `gh api` promotes a request carrying `--input` to POST, so a creation names no method; the two
 // verbs that are not implied by a body do.
@@ -35,6 +36,8 @@ const LABELS_SEGMENT = '/labels'
 const COMMENTS_SEGMENT = '/comments'
 const CLOSED_STATE = 'closed'
 const COLOR_HASH = '#'
+const UNPROCESSABLE_STATUS = 422
+const ALREADY_EXISTS_CODE = 'already_exists'
 
 // The four writers below answered `boolean` under `gh`, and their callers read it: `epic-run.ts`
 // only reports the epic label when it was applied, `epic-relations.ts` counts the relations it
@@ -72,7 +75,7 @@ async function issue_comment(issue_number: string, body: string): Promise<string
 // The same comment, counted rather than thrown. `josh epic --add --decision-file` posts one per child
 // **after** the epic body already carries the record, so a refused comment costs that child's copy and
 // nothing else — an exception there would leave the caller unable to tell a landed insertion from one
-// that wrote nothing (joshuafolkken/kit#1350).
+// that wrote nothing.
 async function issue_try_comment(issue_number: string, body: string): Promise<boolean> {
 	return await did_write_succeed(async () => await issue_comment(issue_number, body))
 }
@@ -85,7 +88,7 @@ async function issue_try_comment(issue_number: string, body: string): Promise<bo
 //
 // **`comment: undefined` closes without commenting**, and it is what the ordering above costs: a run
 // whose comment landed and whose close was refused leaves the issue open carrying the comment, so
-// the next run must close it without posting a second copy (joshuafolkken/kit#1039). The return
+// the next run must close it without posting a second copy. The return
 // value keeps meaning what it meant — with no comment to post, the state change is not merely the
 // last thing attempted but the only one.
 //
@@ -103,23 +106,30 @@ async function issue_close(issue_number: string, comment: string | undefined): P
 	})
 }
 
-// `gh label create` accepted `#5319e7` and stripped the `#` itself; REST answers 422
-// `{"resource":"Label","code":"invalid","field":"color"}` for the same value. The one caller passes
-// the hash form (`EPIC_LABEL_COLOR`), so dropping it here is what keeps that call site unchanged.
+// REST answers 422 `{"resource":"Label","code":"invalid","field":"color"}` for a color carrying a
+// leading `#`. The one caller passes the hash form (`EPIC_LABEL_COLOR`), so dropping it here is what
+// keeps that call site unchanged.
 function to_label_color(color: string): string {
 	return color.startsWith(COLOR_HASH) ? color.slice(COLOR_HASH.length) : color
 }
 
-// `|| true` semantics, unchanged: an existing label answers 422 `already_exists`, which is not an
-// error here.
+// The one failure that means the label is there: 422 with `"code":"already_exists"` in the error
+// document. The status comes from the failed request itself (`git-gh-failure.ts`) and the code from
+// the body `to_gh_error` appends, so a 422 for another reason — an invalid color — is not read as it.
+function is_label_already_exists(error: unknown): boolean {
+	if (gh_failure.failure_of(error)?.status !== UNPROCESSABLE_STATUS) return false
+
+	return error_text.message_of(error).includes(ALREADY_EXISTS_CODE)
+}
+
+// `|| true` semantics: an existing label answers 422 `already_exists`, which is not an error here.
 //
-// **What swallowing it costs did change, and in the safe direction.** Under `gh`, a label this call
-// failed to create surfaced later — `gh issue create --label epic` could not resolve it and failed
-// there. REST does not fail: `POST /issues` with `labels: [...]`, and `POST /issues/{N}/labels`,
-// both **create** a label the repository does not have, with a generated color and no description
-// (measured on joshuafolkken/kit#1026). So a swallowed failure here costs the label's color and
+// **Every other failure is warned about, and still not thrown.** `POST /issues` with
+// `labels: [...]`, and `POST /issues/{N}/labels`, both **create** a label the repository does not
+// have, with a generated color and no description. So a failure here costs the label's color and
 // description, never the label itself — `epic:next` and the auto-close filter on the name, and the
-// name is applied either way.
+// name is applied either way. A 401 / 403, a rate limit or a request that never arrived is named
+// rather than read as "the label already exists".
 async function label_ensure(input: {
 	name: string
 	color: string
@@ -134,17 +144,20 @@ async function label_ensure(input: {
 				description: input.description,
 			}),
 		})
-	} catch {
-		/* the label already exists */
+	} catch (error) {
+		if (is_label_already_exists(error)) return
+		const [gist = ''] = error_text.message_of(error).split('\n', 1)
+
+		console.warn(`⚠ could not create the \`${input.name}\` label — ${gist}`)
 	}
 }
 
 // What creating an issue over REST means, as one value both execution paths build from: the
-// collection to post to, the JSON body, and the `.html_url` unwrap that answers the browser URL
-// `gh issue create` used to print.
+// collection to post to, the JSON body, and the `.html_url` unwrap that answers the issue's browser
+// URL.
 //
 // It exists as a request rather than only as the writer below because `josh propagate` opens its
-// consumer's issue **synchronously** and cannot await (joshuafolkken/kit#1042). Spelling the same
+// consumer's issue **synchronously** and cannot await. Spelling the same
 // three decisions out again at that call site would be a second definition of the same write
 // (`CLAUDE.md` → "No clones"), so the request is shared and only the spawn differs.
 //
@@ -184,7 +197,7 @@ async function issue_create_with_label(input: {
 }
 
 // The outcome of applying one label, with the swallowed failure's gist kept for a caller that has to
-// say why it refused (joshuafolkken/kit#3312).
+// say why it refused.
 type LabelWrite = { is_applied: true } | { is_applied: false; reason: string }
 
 // The issue's label names, read back after a failed write. A read that itself fails answers
@@ -207,7 +220,7 @@ async function read_label_names(issue_number: string): Promise<Array<string> | u
 
 // **A failed answer is not a failed write.** The POST is idempotent, and a timeout, a non-zero exit
 // after the write or a secondary rate limit can each throw after the label landed — which refused a
-// lane dispatch whose label was in fact applied (joshuafolkken/kit#3312). So a throw is confirmed by
+// lane dispatch whose label was in fact applied. So a throw is confirmed by
 // reading the labels back, and only a label that is really absent answers `is_applied: false`.
 async function issue_apply_label(issue_number: string, label: string): Promise<LabelWrite> {
 	const labels_path = `${git_gh_api_path.issue_api_path(issue_number)}${LABELS_SEGMENT}`
@@ -232,15 +245,15 @@ async function issue_apply_label(issue_number: string, label: string): Promise<L
 
 // Applied after the body edit so a failure leaves an issue with the epic sections and no label,
 // which `epic:check` reports — rather than a labelled issue with nothing to track. The caller checks
-// the return: the label is what the auto-close filters on (joshuafolkken/kit#865).
+// the return: the label is what the auto-close filters on.
 async function issue_add_label(issue_number: string, label: string): Promise<boolean> {
 	const write = await issue_apply_label(issue_number, label)
 
 	return write.is_applied
 }
 
-// The counterpart to the addition above, for a run taking its own marker back off
-// (joshuafolkken/kit#1794). **The name travels in the path, so it is encoded**: a label is free to
+// The counterpart to the addition above, for a run taking its own marker back off.
+// **The name travels in the path, so it is encoded**: a label is free to
 // contain a `/` or a `#`, and an unencoded one would address a path that is not this label's.
 //
 // **It throws rather than answering `boolean`**, which is the one place it departs from
@@ -263,8 +276,8 @@ async function issue_remove_label(issue_number: string, label: string): Promise<
 // The endpoint takes `{"issue_id": <n>}` and does not check that `<n>` is an issue in this
 // repository, or that it is the number the caller meant. Posting `{"issue_id":1036}` to a scratch
 // issue in this repository recorded an issue in a completely unrelated repository — the one whose
-// database id happens to be 1036 — as a blocker, with a 200 and no warning (measured on
-// joshuafolkken/kit#1026, which names it). Every caller here names a blocker by its issue number, so
+// database id happens to be 1036 — as a blocker, with a 200 and no warning. Every caller here names
+// a blocker by its issue number, so
 // sending that number would silently record an arbitrary issue from anywhere on GitHub.
 //
 // A resolution that does not produce a usable id throws rather than returning something to send:
@@ -278,16 +291,15 @@ async function read_issue_id(issue_number: string): Promise<number> {
 	const issue_id = Number(raw.trim())
 
 	if (!Number.isSafeInteger(issue_id) || issue_id <= 0) {
-		throw new Error(`gh api answered no database id for issue #${issue_number}`)
+		throw new Error(`gh api answered no database id for issue ${session_cite.issue(issue_number)}`)
 	}
 
 	return issue_id
 }
 
 // Applied after creation, never as part of it: the relation is a nicety and the Issue is not, so a
-// failure here costs only the relation. It no longer depends on the gh CLI's version — the
-// dependencies endpoint is REST, and `gh api` has proxied REST since long before `--add-blocked-by`
-// existed (joshuafolkken/kit#1026).
+// failure here costs only the relation. It does not depend on the gh CLI's version — the
+// dependencies endpoint is REST, which `gh api` proxies.
 async function issue_add_blocked_by(issue_number: string, blocker: string): Promise<boolean> {
 	return await did_write_succeed(async () => {
 		const issue_id = await read_issue_id(blocker)
@@ -300,8 +312,8 @@ async function issue_add_blocked_by(issue_number: string, blocker: string): Prom
 }
 
 // The counterpart, for an insertion that re-points an existing chain: inserting `#N` between `#B`
-// and `#M` has to drop `#B -> #M`, or the epic would declare one order and record two
-// (joshuafolkken/kit#890). The id goes in the path here rather than in a body, and the endpoint is
+// and `#M` has to drop `#B -> #M`, or the epic would declare one order and record two.
+// The id goes in the path here rather than in a body, and the endpoint is
 // idempotent — deleting a relation that is not there answers 200.
 async function issue_remove_blocked_by(issue_number: string, blocker: string): Promise<boolean> {
 	return await did_write_succeed(async () => {

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

@@ -5,17 +5,17 @@ import { git_gh_issue_write } from './git-gh-issue-write'
 
 const NUMBER_AND_BODY_FIELDS = 'number,body'
 // The backlog scan's fields. The title rides along because the pre-filing scan compares titles
-// (joshuafolkken/kit#1252) and it costs nothing: the same listing request already carries it, so the
+// and it costs nothing: the same listing request already carries it, so the
 // two consumers share one read rather than each making their own.
 //
 // `blocked_by_count` rides along for the same reason and is the one field here that `gh --json`
 // never had: it is read out of the `issue_dependencies_summary` the listing response already
-// carries, so it costs no request at all (joshuafolkken/kit#1736). It is what lets `epic:bundle`
+// carries, so it costs no request at all. It is what lets `epic:bundle`
 // tell a row with no blockers from one with some **before** deciding whether that row is worth a
-// per-issue read — the read it used to make for every open issue in the repository. Absent on a row
-// whose summary is missing, which must not be read as zero; `git-gh-issue-rest.ts` states why.
+// per-issue read, which would otherwise be made for every open issue in the repository. Absent on a
+// row whose summary is missing, which must not be read as zero; `git-gh-issue-rest.ts` states why.
 const BACKLOG_SCAN_FIELDS = `number,title,body,${BLOCKED_BY_COUNT_FIELD}`
-// The recently-closed scan's fields (joshuafolkken/kit#1679). It compares titles like the scan above
+// The recently-closed scan's fields. It compares titles like the scan above
 // and never reads a body, and it needs the labels to tell an epic from a deliverable — the open half
 // gets that from the epic listing, which by construction holds no closed epic.
 const NUMBER_TITLE_AND_LABELS_FIELDS = 'number,title,labels'
@@ -26,16 +26,16 @@ const SUMMARY_FIELDS = 'number,title,labels,createdAt'
 // `SUMMARY_FIELDS` on purpose: a listing carries no `blockedBy`, so the field is answered from each
 // row's own dependencies endpoint, and asking for it on the shared list would put that request
 // behind the next-issues display too — where a refused one becomes a failure with no message at all,
-// since the listing swallows the error (joshuafolkken/kit#996, joshuafolkken/kit#1025). `body` costs
+// since the listing swallows the error. `body` costs
 // no request — the REST listing row already carries it — and is what the backlog offer reads for
-// the restructures each issue declares (joshuafolkken/kit#3221).
+// the paths each issue declares.
 const PICKUP_FIELDS = `${SUMMARY_FIELDS},blockedBy,body`
 
 // Every listing below goes through the one REST invocation in `git-gh-issue-list.ts`. It kept the
 // `json_fields` / `limit` contract it had as a `gh issue list` wrapper, so these callers changed
-// only where a `gh` flag became a query parameter (joshuafolkken/kit#1025).
+// only where a `gh` flag became a query parameter.
 //
-// **They all answer `IssueListOutcome`, not the JSON alone** (joshuafolkken/kit#1067). The page
+// **They all answer `IssueListOutcome`, not the JSON alone**. The page
 // ceiling now bounds every one of them, and a bound whose caller cannot see it was reached is a
 // silently shortened answer — so the flag rides out to the caller and the caller decides. The
 // disposition each one settled on, and why:
@@ -44,18 +44,18 @@ const PICKUP_FIELDS = `${SUMMARY_FIELDS},blockedBy,body`
 // | --- | --- | --- |
 // | `issue_list_recent` | **ignorable** | The display shows the five newest of the twenty it asks for, and the paging is newest-first — so a truncated read is a *prefix* of the untruncated one and the five rows are the same five. Nothing is hidden that this display would have shown. |
 // | `issue_list_open_bodies` | **warning** | `epic:bundle` scanned what it scanned; a related issue past the cut is missed, which is what its existing `⚠ … cap` line already says. The scan ran, so it is something to read rather than a check that did not happen. |
-// | `issue_search_body` | **warning** | Unchanged from joshuafolkken/kit#1033 — the orphan search ran over the newest issues, and an orphan is normally an issue filed minutes ago. |
+// | `issue_search_body` | **warning** | The orphan search runs over the newest issues, and an orphan is normally an issue filed minutes ago. |
 // | `issue_list_by_label` | **warning** | Both consumers report it: `epic:bundle`'s epic listing, where an epic past the cut has its child recommended a second epic, and the auto-close, where an epic past the cut is never checked for completion. Neither may fail — the auto-close runs after the merge — so both print and continue. |
 // | `issue_list_by_label_summary` | **warning** | The `auto-ok` pickup already says the cap dropped the *oldest* opted-in issues; the ceiling drops the same ones. The answer it gives is still opted in, just possibly not the highest-priority one. |
 // | `issue_list_recently_closed` | **warning** | `issue:scout` widens its duplicate scan over what closed recently; a closed issue past the cut is one candidate the reader is not shown, exactly as on the open half. The scan ran, so it is reported beside the open one rather than failing the command. |
-// | `issue_list_by_label_in_repo` | **error** | `epic:busy` asks whether a repository already has work running in it, and it is the only one whose answer *authorizes an action*. A truncated listing with no visible holder is not "nothing is running", and reading it as one starts a second run in the same checkout — the direction joshuafolkken/kit#925 closed. It lands with the unreadable listing, on `wait`. It is also the only caller that reports the page ceiling **without** the `limit` cap beside it; `epic-busy.ts` records why a full page of parked issues must not latch the guard. |
+// | `issue_list_by_label_in_repo` | **error** | `epic:busy` asks whether a repository already has work running in it, and it is the only one whose answer *authorizes an action*. A truncated listing with no visible holder is not "nothing is running", and reading it as one starts a second run in the same checkout. It lands with the unreadable listing, on `wait`. It is also the only caller that reports the page ceiling **without** the `limit` cap beside it; `epic-busy.ts` records why a full page of parked issues must not latch the guard. |
 //
-// The split is joshuafolkken/kit#1033's, applied caller by caller rather than copied: truncation is
+// The split is applied caller by caller rather than copied: truncation is
 // a warning where the scan *ran* and an error where the answer it produced would authorize an
 // action. Only `epic:busy` authorizes one.
 const { issue_list } = git_gh_issue_list
 
-// The newest open issues, for the next-issues display at workflow completion (#821). `createdAt`
+// The newest open issues, for the next-issues display at workflow completion. `createdAt`
 // rides along because the caller re-sorts explicitly rather than inheriting the listing's order.
 async function issue_list_recent(limit: number): Promise<IssueListOutcome> {
 	return await issue_list({ json_fields: SUMMARY_FIELDS, limit })
@@ -63,15 +63,14 @@ async function issue_list_recent(limit: number): Promise<IssueListOutcome> {
 
 // Every open issue with its title and body. Used by `epic:bundle` to scan the backlog and by
 // `issue:scout` to compare titles before one is filed; a search with an empty term is not a listing,
-// and asking `gh` for one produced a partial and arbitrary answer (joshuafolkken/kit#873).
+// and asking `gh` for one produced a partial and arbitrary answer.
 async function issue_list_open_bodies(limit: number): Promise<IssueListOutcome> {
 	return await issue_list({ json_fields: BACKLOG_SCAN_FIELDS, limit })
 }
 
-// The issues that closed most recently, for the duplicate half of `issue:scout`
-// (joshuafolkken/kit#1679). **The work most likely to be filed twice is the work that just
-// finished** — joshuafolkken/kit#1656 was filed about five hours after joshuafolkken/kit#1623 closed
-// having already done it — and a scan that reads only open issues cannot see any of it.
+// The issues that closed most recently, for the duplicate half of `issue:scout`.
+// **The work most likely to be filed twice is the work that just
+// finished**, and a scan that reads only open issues cannot see any of it.
 //
 // `sort=updated` rather than `created`: the question is what closed recently, and a listing ordered
 // by filing date puts a five-year-old issue closed this morning behind whatever was filed yesterday.
@@ -95,11 +94,11 @@ async function issue_list_recently_closed(limit: number): Promise<IssueListOutco
 }
 
 // Open issues whose body mentions `term`. Used by `epic:audit` to find an issue that names an epic
-// as its parent while the epic's task list does not track it (joshuafolkken/kit#870).
+// as its parent while the epic's task list does not track it.
 //
 // The one listing here whose filter runs client-side, and so the one that reaches the page ceiling
 // on an ordinary repository: its matches are normally zero, so "stop once `limit` rows are selected"
-// never fires for it (joshuafolkken/kit#1033).
+// never fires for it.
 async function issue_search_body(term: string, limit: number): Promise<IssueListOutcome> {
 	return await issue_list({
 		json_fields: NUMBER_AND_BODY_FIELDS,
@@ -112,13 +111,13 @@ async function issue_list_by_label(label: string, limit: number): Promise<IssueL
 	return await issue_list({ json_fields: NUMBER_AND_BODY_FIELDS, limit, label })
 }
 
-// The same filter with the fields the `auto-ok` pickup needs (joshuafolkken/kit#906): it orders by
-// `createdAt`, re-checks `labels` client-side and reads each body for its declared restructures. A
+// The same filter with the fields the `auto-ok` pickup needs: it orders by
+// `createdAt`, re-checks `labels` client-side and reads each body for its declared paths. A
 // label that does not exist in the repository is not an error — the listing comes back empty, which
 // is exactly "nobody has opted anything in".
 // `json_fields` overrides the pickup's list. Its only caller is the probe that runs *after* a failed
 // read, asking the same question without `blockedBy` so a refused dependencies endpoint is told
-// apart from an access failure (joshuafolkken/kit#1005).
+// apart from an access failure.
 async function issue_list_by_label_summary(
 	label: string,
 	limit: number,
@@ -132,7 +131,7 @@ async function issue_list_by_label_summary(
 }
 
 // Open issues carrying `label` in one named repository — the read `epic:next` makes before it
-// offers a child, to see whether that repository already has one running (joshuafolkken/kit#925).
+// offers a child, to see whether that repository already has one running.
 //
 // `SUMMARY_FIELDS` rather than `PICKUP_FIELDS`: the answer is only "which issues hold this
 // repository", and asking for `blockedBy` would put a dependencies request behind the guard — where

package/scripts/gh/git-gh-pr-auto-merge.ts

@@ -4,14 +4,14 @@ import { git_gh_exec } from './git-gh-exec'
 import { read_pull, require_pr_number } from './git-gh-pr-read'
 import { git_gh_pr_rest, type RestPull } from './git-gh-pr-rest'
 
-// Auto-merge for a pull request a josh command opens and would otherwise have to stay alive to land
-// (joshuafolkken/kit#2497). `pnpm josh observations:flush` used to merge its pull request only from
+// Auto-merge for a pull request a josh command opens and would otherwise have to stay alive to land.
+// `pnpm josh observations:flush` used to merge its pull request only from
 // inside its own wait, so a wait that ended early — a session cut, a killed process — left a green
 // pull request open with nobody to merge it.
 //
 // **This is the one GraphQL request in the pull-request layer, because REST has no equivalent.**
 // Enabling auto-merge is `enablePullRequestAutoMerge` and nothing else. A cloud session can be
-// answered 403 for GraphQL (joshuafolkken/kit#1022), so the caller treats a failure here as a lost
+// answered 403 for GraphQL, so the caller treats a failure here as a lost
 // safety net rather than a failed command — the in-process wait still merges as it always did.
 
 const GRAPHQL_PATH = 'graphql'

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

@@ -4,17 +4,16 @@ import { git_gh_helpers } from './git-gh-helpers'
 import { git_gh_pr_rest, type RestPull } from './git-gh-pr-rest'
 import { to_gh_state } from './git-gh-rest-state'
 
-// Reading pull requests through REST, in the answers `gh pr view` used to give.
+// Reading pull requests through REST, in the answers `gh pr view` gives.
 //
-// `gh pr view` goes through GraphQL, which a cloud session is answered 403 for (joshuafolkken/kit#1022).
+// `gh pr view` goes through GraphQL, which a cloud session is answered 403 for.
 // The reads move to `gh api`, and every caller downstream keeps the contract it already reads — the
 // empty string from `pr_view`, `undefined` from the two comment readers. `pr_exists` is the one
 // exception, and it is deliberate: it gates a **write**, so a lookup that failed cannot answer
-// `false` there (joshuafolkken/kit#1043).
+// `false` there.
 //
 // One thing has no counterpart in REST: `gh pr view` accepted a **branch name** and every REST
-// endpoint is keyed by **number**. The resolution below is the single place that bridges the two
-// (joshuafolkken/kit#1027).
+// endpoint is keyed by **number**. The resolution below is the single place that bridges the two.
 
 // The branch → number resolution, remembered for the life of the process.
 //
@@ -35,22 +34,21 @@ const pr_number_by_branch = new Map<string, number>()
 // most recent one" while this ordering holds.
 const LOOKUP_QUERY = 'state=all&sort=created&direction=desc&per_page=100'
 // The comment listings are paged: REST answers 30 rows by default, while `gh pr view --json comments`
-// answered the whole conversation. Truncating them is the kit#973 failure again in another form — the
-// newest Claude Review blocker falls off a listing that is ordered oldest first, and the merge gate
-// finds nothing to stop on. `gh api --paginate` merges the pages of an array endpoint into one array,
-// so the answer stays the flat listing every caller parses. The page size itself is
-// `FULL_PAGE_QUERY`, shared with the merge-gate listings (joshuafolkken/kit#1028).
+// answers the whole conversation. Truncating them lets the merge gate pass on a listing it never
+// fully read — the newest Claude Review blocker falls off a listing that is ordered oldest first,
+// and the merge gate finds nothing to stop on. `gh api --paginate` merges the pages of an array
+// endpoint into one array, so the answer stays the flat listing every caller parses. The page size
+// itself is `FULL_PAGE_QUERY`, shared with the merge-gate listings.
 const COMMENTS_QUERY = FULL_PAGE_QUERY
 // Written as a constant rather than inline: `{owner}` inside a template literal reads as a broken
 // interpolation.
 const OWNER_PLACEHOLDER = '{owner}'
 // What a branch-keyed caller that cannot fold an absence into its own answer throws. Lives here
 // rather than beside either caller: the merge-gate snapshot and the two branch-keyed writes all need
-// it, and three copies of one message is the clone `CLAUDE.md` prohibits (joshuafolkken/kit#1029).
+// it, and three copies of one message is the clone `CLAUDE.md` prohibits.
 const NO_PULL_REQUEST_MESSAGE = 'gh api found no pull request for branch'
 // And what it throws when the lookup never answered at all. Separate from the message above because
-// the two are different diagnoses: one says the branch has nothing, the other says nobody looked
-// (joshuafolkken/kit#1048).
+// the two are different diagnoses: one says the branch has nothing, the other says nobody looked.
 const UNREADABLE_PULL_REQUEST_MESSAGE = 'gh api could not read the pull requests for branch'
 
 // `head` names the owner of the head repository, which for every branch this tooling opens is the
@@ -74,15 +72,15 @@ async function fetch_pr_number(branch_name: string): Promise<number | undefined>
 // auth, a dropped connection, a 200 carrying something other than a listing.
 //
 // The vocabulary is `IssueRead`'s in `git-gh-issue-read.ts`, which tells the same two apart for an
-// issue number (joshuafolkken/kit#957); reusing it rather than inventing a second spelling for one
+// issue number; reusing it rather than inventing a second spelling for one
 // distinction is the point. The *classification* is cheaper here and needs no status probe: a branch
 // with no pull request is a 200 with an empty listing rather than a 404, so the lookup's own outcome
-// already separates them (joshuafolkken/kit#1048).
+// already separates them.
 interface PullMergeState {
 	is_merged: boolean
 	merged_at: string | undefined
 	head_sha: string | undefined
-	// `josh ship` reads `DIRTY` here to re-merge a conflicting pull request (joshuafolkken/kit#3221).
+	// `josh ship` reads `DIRTY` here to re-merge a conflicting pull request.
 	merge_state_status: string | undefined
 }
 
@@ -90,15 +88,15 @@ type PullNumberRead =
 	{ kind: 'read'; pr_number: number } | { kind: 'missing' } | { kind: 'unreadable'; cause: unknown }
 
 // The branch-keyed detail read, in the same three answers. `missing` and `unreadable` are the
-// resolution's own; `unreadable` also covers a resolved number whose detail read failed, which every
-// branch-keyed reader used to fold into "no pull request" (joshuafolkken/kit#3263).
+// resolution's own; `unreadable` also covers a resolved number whose detail read failed, so no
+// branch-keyed reader folds it into "no pull request".
 type PullRead = Exclude<PullNumberRead, { kind: 'read' }> | { kind: 'read'; pull: RestPull }
 
 // The lookups still in flight, keyed the same way the resolved numbers are.
 const pending_pr_number_by_branch = new Map<string, Promise<PullNumberRead>>()
 
-// The detail reads, keyed by number and remembered for the life of the command
-// (joshuafolkken/kit#3263). `josh followup` asks `pr_get_body` and `pr_get_url` in one tick — the
+// The detail reads, keyed by number and remembered for the life of the command.
+// `josh followup` asks `pr_get_body` and `pr_get_url` in one tick — the
 // same `GET /pulls/{N}` each time. The promise is stored, so readers in one tick share the request as
 // well as its answer; a read that fails is dropped and re-tried, the rule the number memo holds.
 // **Every write to a pull request clears it** through `forget_pr_numbers`, and the two state readers
@@ -119,7 +117,7 @@ async function fetch_pr_number_read(branch_name: string): Promise<PullNumberRead
 	}
 }
 
-// **The lookup in flight is shared, not only the number it resolves to** (joshuafolkken/kit#1446).
+// **The lookup in flight is shared, not only the number it resolves to**.
 // The memo above answers a caller arriving *after* the first lookup returned, which was every caller
 // while the branch-keyed reads were issued one at a time. `josh followup` now asks `pr_get_body` and
 // `pr_get_url` about the same branch in the same tick, and two callers that both miss an empty map
@@ -170,22 +168,21 @@ async function resolve_pr_number(branch_name: string): Promise<number | undefine
 }
 
 // One definition, because both callers that refuse to fold an unreadable lookup raise it —
-// `require_pr_number` and `pr_exists` (joshuafolkken/kit#1043).
+// `require_pr_number` and `pr_exists`.
 function to_unreadable_error(branch_name: string, cause: unknown): Error {
 	return new Error(`${UNREADABLE_PULL_REQUEST_MESSAGE}: ${branch_name}`, { cause })
 }
 
 // The number for a caller that has nothing to fold an absence into. The reads above answer their own
 // empty value for a branch with no pull request; a write cannot — `gh pr comment <branch>` and
-// `gh pr merge <branch>` both failed there, and the merge-gate snapshot already threw for the same
-// reason. One throw shared by all three (joshuafolkken/kit#1029).
+// `gh pr merge <branch>` both fail there, and the merge-gate snapshot throws for the same reason.
+// One throw shared by all three.
 //
-// **This is the caller the distinction was written for.** Folding both into
-// `NO_PULL_REQUEST_MESSAGE` reported a rate-limited lookup as "there is no pull request for this
-// branch" — safe, in that the run stops without merging, but wrong about why, which is the
-// joshuafolkken/kit#973 misread costing diagnosis time instead of correctness. The failure travels as
-// the `cause`, so `git_error.handle` prints gh's own reason under 💡 Details
-// (joshuafolkken/kit#1048).
+// **This is the caller the distinction matters most for.** Folding both into
+// `NO_PULL_REQUEST_MESSAGE` would report a rate-limited lookup as "there is no pull request for this
+// branch" — safe, in that the run stops without merging, but wrong about why, which costs diagnosis
+// time instead of correctness. The failure travels as
+// the `cause`, so `git_error.handle` prints gh's own reason under 💡 Details.
 async function require_pr_number(branch_name: string): Promise<number> {
 	const read = await read_pr_number(branch_name)
 	if (read.kind === 'read') return read.pr_number
@@ -239,13 +236,13 @@ async function read_pull_or_undefined(branch_name: string): Promise<RestPull | u
 	return read.kind === 'read' ? read.pull : undefined
 }
 
-// **`false` means the branch has no pull request, and nothing else.** This is the second half of
-// joshuafolkken/kit#1048's distinction, on the caller that needs it most: `pr_exists` is not read for
-// display, it decides whether `git-pr.ts` **opens** a pull request. Folding an unreadable lookup into
-// `false` therefore made a rate-limited run try to create a second pull request on a branch that
-// already had one — surviving only because `pr_create`'s 422 → `PR_ALREADY_EXISTS` recovery caught it
-// (joshuafolkken/kit#1029), which is an accident rather than a design. The throw is the one
-// `require_pr_number` raises, so gh's own reason travels as the `cause` (joshuafolkken/kit#1043).
+// **`false` means the branch has no pull request, and nothing else.** This is the same
+// missing-versus-unreadable distinction, on the caller that needs it most: `pr_exists` is not read
+// for display, it decides whether `git-pr.ts` **opens** a pull request. Folding an unreadable lookup
+// into `false` would make a rate-limited run try to create a second pull request on a branch that
+// already has one — surviving only if `pr_create`'s 422 → `PR_ALREADY_EXISTS` recovery caught it,
+// which is an accident rather than a design. The throw is the one
+// `require_pr_number` raises, so gh's own reason travels as the `cause`.
 async function pr_exists(branch_name: string): Promise<boolean> {
 	const read = await read_pr_number(branch_name)
 	if (read.kind === 'unreadable') throw to_unreadable_error(branch_name, read.cause)
@@ -264,12 +261,12 @@ async function pr_get_url(branch_name: string): Promise<string | undefined> {
 	return git_gh_helpers.parse_pr_state_string(pull.html_url)
 }
 
-// **Where the branch's pull request stands** — a merge a person made by hand included
-// (joshuafolkken/kit#3023): whether it merged and when, and the commit its head is on, which a push
+// **Where the branch's pull request stands** — a merge a person made by hand included:
+// whether it merged and when, and the commit its head is on, which a push
 // made on GitHub moves without touching the local branch. `undefined` covers both "no pull request"
 // and "nothing could be read": `followup` then takes its ordinary path, whose merge step settles a
 // pull request that did merge after all (`pr_merge`), so an unread answer costs a wait, not a wrong tail.
-// Read past the detail memo: `josh ship` asks it again after each merge it pushes (joshuafolkken/kit#3263).
+// Read past the detail memo: `josh ship` asks it again after each merge it pushes.
 async function pr_get_merge_state(branch_name: string): Promise<PullMergeState | undefined> {
 	const read = await read_pull_of_branch(branch_name, read_pull)
 	if (read.kind !== 'read') return undefined
@@ -283,8 +280,8 @@ async function pr_get_merge_state(branch_name: string): Promise<PullMergeState |
 	}
 }
 
-// REST answers JSON null for a pull request with no body where `gh --json body` answered an empty
-// string, and both used to arrive here as the empty answer this folds to `undefined`.
+// REST answers JSON null for a pull request with no body where `gh --json body` answers an empty
+// string; both are the empty answer this folds to `undefined`.
 async function pr_get_body(branch_name: string): Promise<string | undefined> {
 	const pull = await read_pull_or_undefined(branch_name)
 	const body = pull?.body
@@ -295,7 +292,7 @@ async function pr_get_body(branch_name: string): Promise<string | undefined> {
 // The empty string means "this branch has no pull request", and nothing else. A read that failed
 // throws, carrying gh's reason as the `cause`: `git-pr.ts` decides from this state whether the
 // branch's pull request merged, and a rate limit answered as "no state" sent a merged pull request
-// down the open one's path (joshuafolkken/kit#3263). Read past the detail memo, like the merge state.
+// down the open one's path. Read past the detail memo, like the merge state.
 async function pr_view(branch_name: string): Promise<string> {
 	const read = await read_pull_of_branch(branch_name, read_pull)
 	if (read.kind === 'unreadable') throw to_unreadable_error(branch_name, read.cause)
@@ -305,11 +302,11 @@ async function pr_view(branch_name: string): Promise<string> {
 }
 
 // `undefined` when the listing could not be read — a failed request, or a PR whose number could not
-// be resolved. Not `'[]'`, which every failure used to become.
+// be resolved. Not `'[]'`.
 //
-// The two are the same string to a caller, and the callers are the merge gate: a rate limit arrived
-// as "no reviewer left a finding" and the PR merged with the gate never actually read
-// (joshuafolkken/kit#973). The direction is what makes it worse than the epic auto-close's version of
+// The two are the same string to a caller, and the callers are the merge gate: a rate limit would
+// arrive as "no reviewer left a finding" and the PR merge with the gate never actually read.
+// The direction is what makes it worse than the epic auto-close's version of
 // the same misread — that one only failed to close something.
 async function read_comments(
 	branch_name: string,
@@ -332,7 +329,7 @@ function to_comments_json(raw: string): string {
 }
 
 // `git-pr-coderabbit.ts` parses `html_url` and `user.login` itself, so the review thread is handed on
-// as REST serves it (joshuafolkken/kit#1023).
+// as REST serves it.
 function as_served(raw: string): string {
 	return raw
 }
@@ -360,8 +357,7 @@ const git_gh_pr_read = {
 
 // The merge-gate snapshot needs the same branch → number resolution and the same detail read, and it
 // needs them separately: the reviews endpoint is keyed by number while the rollup is keyed by the
-// head commit the detail carries. Exported rather than re-derived so the memo above stays one memo
-// (joshuafolkken/kit#1028).
+// head commit the detail carries. Exported rather than re-derived so the memo above stays one memo.
 export type { PullMergeState }
 export {
 	git_gh_pr_read,