@joshuafolkken/kit 1.1784.0 → 1.2114.0

package/scripts/issue/issue-sample-gate.ts

@@ -1,6 +1,3 @@
-import { read_pull } from '#scripts/gh/git-gh-pr-read'
-import { git_closes_keyword } from '#scripts/git/git-closes-keyword'
-import { lane_ledger } from '#scripts/lane/lane-ledger'
 import { issue_cite } from './issue-cite'
 import { markdown_section } from './markdown-section'
 
@@ -14,23 +11,40 @@ import { markdown_section } from './markdown-section'
 // the wait needs — when the pull request merged — is read ahead by `prime`, once per pull request per
 // process, wherever bodies first arrive. A body nobody primed reads as waiting: offering it early is
 // the defect this guards, and the next primed read releases it.
+//
+// joshuafolkken/kit#5220: the reads `prime` makes — the pull request and the lane ledger — live in
+// `issue-sample-prime.ts`, which hands this module the ledger's merges. The readers that only judge a
+// body import this module alone, so a change to the ledger's reading never reaches their suites.
+//
+// joshuafolkken/kit#5051: a lane files its measurement follow-up before its own pull request exists —
+// `josh ship` wants the deferral row first. So the condition may cite the issue instead (`CLOSING_FORMAT`),
+// and `prime` resolves the merged pull request that closes it; until one exists the body waits as
+// unmerged.
 
 const BACKGROUND_HEADING = '## 背景'
 const PREFIX = '- 実施可能条件:'
-const CONDITION_PATTERN = /^#(?<pr>[1-9]\d*) のマージ後 (?<count>[1-9]\d*) マージ$/u
+const CONDITION_PATTERN =
+	/^#(?<cited>[1-9]\d*) (?<closing>を閉じる PR )?のマージ後 (?<count>[1-9]\d*) マージ$/u
 const VALUE_FORMAT = '#<PR> のマージ後 <K> マージ'
+const CLOSING_FORMAT = '#<issue> を閉じる PR のマージ後 <K> マージ'
 const DECLARATION = `${PREFIX} ${VALUE_FORMAT}`
-const MALFORMED = `\`${PREFIX}\` must read \`${VALUE_FORMAT}\` with K at least 1`
+// The refusal ends in a line ready to paste (joshuafolkken/kit#5225).
+const EXAMPLE = `${PREFIX} #5198 のマージ後 30 マージ`
+const MALFORMED = `\`${PREFIX}\` must read \`${VALUE_FORMAT}\` or \`${CLOSING_FORMAT}\` with K at least 1\n${EXAMPLE}`
+
+// `pull` cites the pull request itself, `issue` the issue whose closing pull request it waits on.
+type Via = 'pull' | 'issue'
 
 interface Condition {
-	pr: number
+	cited: number
+	via: Via
 	count: number
 }
 
 type SampleWait =
-	| { kind: 'unread'; pr: number }
-	| { kind: 'unmerged'; pr: number }
-	| { kind: 'short'; pr: number; counted: number; needed: number }
+	| { kind: 'unread'; cited: number; via: Via }
+	| { kind: 'unmerged'; cited: number; via: Via }
+	| { kind: 'short'; cited: number; via: Via; counted: number; needed: number }
 
 // One pull request as read: `merged_at` absent is one found unmerged, read again as it may merge since.
 // `closes` is the issue its body closes, whose ledger merge is the pull request's own.
@@ -39,19 +53,26 @@ interface PullRead {
 	closes: number | undefined
 }
 
-interface PrimePorts {
-	pull: (pr: number) => Promise<PullRead>
-	ledger_path: () => Promise<string | undefined>
+// One merge the lane ledger recorded, keyed by the issue its pull request closed.
+interface MergeSample {
+	at: string
+	issue: number
 }
 
+// The ledger's merges as they read now; none until a prime has handed them over.
 interface LedgerState {
-	path: string | undefined
+	merges: () => ReadonlyArray<MergeSample>
 }
 
-// A pull request with no entry was never read.
+// A cited number with no entry was never read. Keyed by `key_of`, as one number may be cited both ways.
+
+const pull_by_key = new Map<string, PullRead>()
+
+function no_merges(): ReadonlyArray<MergeSample> {
+	return []
+}
 
-const pull_by_number = new Map<number, PullRead>()
-const ledger: LedgerState = { path: undefined }
+const ledger: LedgerState = { merges: no_merges }
 
 function declared_value(body: string): string | undefined {
 	const background = markdown_section.section_lines(body, BACKGROUND_HEADING).join('\n')
@@ -63,6 +84,10 @@ function declared_value(body: string): string | undefined {
 	return line?.slice(PREFIX.length).trim()
 }
 
+function via_of(groups: Partial<Record<string, string>>): Via {
+	return groups['closing'] === undefined ? 'pull' : 'issue'
+}
+
 // The declared condition, or `undefined` when there is none or it does not parse — a malformed one is
 // refused by `issue:lint`, and holding a hand-edited one forever would lose the issue silently.
 function condition_of(body = ''): Condition | undefined {
@@ -70,12 +95,23 @@ function condition_of(body = ''): Condition | undefined {
 
 	if (groups === undefined) return undefined
 
-	return { pr: Number(groups['pr']), count: Number(groups['count']) }
+	return { cited: Number(groups['cited']), via: via_of(groups), count: Number(groups['count']) }
 }
 
 // The number the declared condition cites, or `undefined` when there is none or it does not parse.
 function cited_number(body: string): number | undefined {
-	return condition_of(body)?.pr
+	return condition_of(body)?.cited
+}
+
+// The number cited by the given form only — the issue form cites an issue by design.
+function cited_via(body: string, via: Via): number | undefined {
+	const condition = condition_of(body)
+
+	return condition?.via === via ? condition.cited : undefined
+}
+
+function key_of({ cited, via }: Pick<Condition, 'cited' | 'via'>): string {
+	return `${via}:${String(cited)}`
 }
 
 function problems(body: string): ReadonlyArray<string> {
@@ -84,63 +120,38 @@ function problems(body: string): ReadonlyArray<string> {
 	return value === undefined || CONDITION_PATTERN.test(value) ? [] : [MALFORMED]
 }
 
-async function read_source(pr: number): Promise<PullRead> {
-	const pull = await read_pull(pr)
-	const closes = git_closes_keyword.parse_closes_issue_number(pull.body ?? undefined)
+// Keeps what a prime read for the condition; `undefined` — a failed read — leaves it unread.
+function record(condition: Condition, pull: PullRead | undefined): void {
+	const key = key_of(condition)
 
-	return {
-		merged_at: pull.merged_at ?? undefined,
-		closes: closes === undefined ? undefined : Number(closes),
-	}
+	if (pull === undefined) pull_by_key.delete(key)
+	else pull_by_key.set(key, pull)
 }
 
-const DEFAULT_PORTS: PrimePorts = { pull: read_source, ledger_path: lane_ledger.target }
-
-// A failed read stays unread, so the next prime asks again.
-async function remember(pr: number, ports: PrimePorts): Promise<void> {
-	try {
-		pull_by_number.set(pr, await ports.pull(pr))
-	} catch {
-		pull_by_number.delete(pr)
-	}
+function use_merges(merges: () => ReadonlyArray<MergeSample>): void {
+	ledger.merges = merges
 }
 
-function is_merge_known(pr: number): boolean {
-	return pull_by_number.get(pr)?.merged_at !== undefined
+function is_merge_known(condition: Condition): boolean {
+	return pull_by_key.get(key_of(condition))?.merged_at !== undefined
 }
 
-// Reads ahead what the bodies' conditions need. Nothing is read for bodies that declare none.
-async function prime(
-	bodies: ReadonlyArray<string | undefined>,
-	ports: PrimePorts = DEFAULT_PORTS,
-): Promise<void> {
+// The conditions the bodies declare whose pull request has not been read merged, one per key.
+function unread_of(bodies: ReadonlyArray<string | undefined>): Array<Condition> {
 	const unread = bodies
-		.map((body) => condition_of(body)?.pr)
-		.filter((pr): pr is number => pr !== undefined && !is_merge_known(pr))
-
-	if (unread.length === 0) return
+		.map((body) => condition_of(body))
+		.filter(
+			(condition): condition is Condition => condition !== undefined && !is_merge_known(condition),
+		)
 
-	ledger.path = await ports.ledger_path()
-	await Promise.all(
-		[...new Set(unread)].map(async (pr) => {
-			await remember(pr, ports)
-		}),
-	)
+	return [...new Map(unread.map((condition) => [key_of(condition), condition])).values()]
 }
 
 function merges_after({ merged_at, closes }: PullRead & { merged_at: string }): number {
-	if (ledger.path === undefined) return 0
-
 	const since = Date.parse(merged_at)
 
-	return lane_ledger
-		.read_entries(ledger.path)
-		.filter(
-			(entry) =>
-				entry.kind === lane_ledger.KIND.MERGE &&
-				entry.issue !== closes &&
-				Date.parse(entry.at) > since,
-		).length
+	return ledger.merges().filter((merge) => merge.issue !== closes && Date.parse(merge.at) > since)
+		.length
 }
 
 // What the body still waits on, or `undefined` when it declares nothing or has its samples.
@@ -149,44 +160,54 @@ function wait_of(body?: string): SampleWait | undefined {
 
 	if (condition === undefined) return undefined
 
-	const { pr, count } = condition
-	const pull = pull_by_number.get(pr)
+	const { cited, via, count } = condition
+	const pull = pull_by_key.get(key_of(condition))
 
-	if (pull === undefined) return { kind: 'unread', pr }
+	if (pull === undefined) return { kind: 'unread', cited, via }
 
 	const { merged_at, closes } = pull
 
-	if (merged_at === undefined) return { kind: 'unmerged', pr }
+	if (merged_at === undefined) return { kind: 'unmerged', cited, via }
 
 	const counted = merges_after({ merged_at, closes })
 
-	return counted >= count ? undefined : { kind: 'short', pr, counted, needed: count }
+	return counted >= count ? undefined : { kind: 'short', cited, via, counted, needed: count }
+}
+
+function subject_of({ cited, via }: SampleWait): string {
+	const plain = issue_cite.plain(cited)
+
+	return via === 'pull' ? plain : `the pull request closing ${plain}`
 }
 
 // Why the body waits, for a reader that cites the issue itself.
 function reason_of(wait: SampleWait): string {
-	const pr = issue_cite.plain(wait.pr)
+	const subject = subject_of(wait)
 
-	if (wait.kind === 'unread') return `until the merge of ${pr} is read`
-	if (wait.kind === 'unmerged') return `until ${pr} merges`
+	if (wait.kind === 'unread') return `until the merge of ${subject} is read`
+	if (wait.kind === 'unmerged') return `until ${subject} merges`
 
-	return `${String(wait.counted)}/${String(wait.needed)} merges after ${pr}`
+	return `${String(wait.counted)}/${String(wait.needed)} merges after ${subject}`
 }
 
 function reset(): void {
-	pull_by_number.clear()
-	ledger.path = undefined
+	pull_by_key.clear()
+	ledger.merges = no_merges
 }
 
 const issue_sample_gate = {
 	DECLARATION,
+	CLOSING_FORMAT,
 	cited_number,
-	prime,
+	cited_via,
 	problems,
 	reason_of,
+	record,
 	reset,
+	unread_of,
+	use_merges,
 	wait_of,
 }
 
-export type { PrimePorts, SampleWait }
+export type { Condition, MergeSample, PullRead, SampleWait }
 export { issue_sample_gate }

package/scripts/issue/issue-sample-prime.ts

@@ -0,0 +1,127 @@
+import { git_gh_api_path } from '#scripts/gh/git-gh-api-path'
+import { git_gh_exec } from '#scripts/gh/git-gh-exec'
+import { git_gh_issue_rest } from '#scripts/gh/git-gh-issue-rest'
+import { read_pull } from '#scripts/gh/git-gh-pr-read'
+import { git_gh_pr_too_large } from '#scripts/gh/git-gh-pr-too-large'
+import { git_closes_keyword } from '#scripts/git/git-closes-keyword'
+import { lane_ledger, type MergeEntry } from '#scripts/lane/lane-ledger'
+import { issue_closing_pr } from './issue-closing-pr'
+import {
+	issue_sample_gate,
+	type Condition,
+	type MergeSample,
+	type PullRead,
+} from './issue-sample-gate'
+
+// The reads `issue_sample_gate` waits on, made ahead where bodies first arrive (joshuafolkken/kit#4414):
+// when the cited pull request merged, and the merges the lane ledger recorded. Kept apart from the
+// gate so that only the primers reach the ledger's reader (joshuafolkken/kit#5220).
+
+// The two fields `read_source` takes from a pull request, whichever endpoint served them.
+interface PullFields {
+	body?: string | null | undefined
+	merged_at?: string | null | undefined
+}
+
+// `closing` reads the pull request that closes an issue; one not merged yet reads as unmerged.
+interface PrimePorts {
+	pull: (pr: number) => Promise<PullRead>
+	closing: (issue: number) => Promise<PullRead>
+	ledger_path: () => Promise<string | undefined>
+}
+
+// joshuafolkken/kit#5241: GitHub refuses the single pull request read of a large one with 422 `too many
+// files changed`, and a closing number carries no branch to read the listing row by. The issue
+// endpoint serves the same pull request's body and merge time.
+async function read_as_issue(pr: number): Promise<PullFields> {
+	const json = await git_gh_exec.exec_gh_api({ path: git_gh_api_path.issue_api_path(String(pr)) })
+	const issue = git_gh_issue_rest.parse_rest_issue(json)
+
+	return { body: issue.body, merged_at: issue.pull_request?.merged_at }
+}
+
+async function read_fields(pr: number): Promise<PullFields> {
+	try {
+		return await read_pull(pr)
+	} catch (error) {
+		if (!git_gh_pr_too_large.is_too_many_files(error)) throw error
+
+		return await read_as_issue(pr)
+	}
+}
+
+async function read_source(pr: number): Promise<PullRead> {
+	const pull = await read_fields(pr)
+	const closes = git_closes_keyword.parse_closes_issue_number(pull.body ?? undefined)
+
+	return {
+		merged_at: pull.merged_at ?? undefined,
+		closes: closes === undefined ? undefined : Number(closes),
+	}
+}
+
+// The merged pull request closing the issue; `closes` is the issue itself, whichever pull request it is.
+async function read_closing_source(issue: number): Promise<PullRead> {
+	const pr = await issue_closing_pr.read_closing_number(issue)
+
+	if (pr === undefined) return { merged_at: undefined, closes: issue }
+
+	const { merged_at } = await read_source(pr)
+
+	return { merged_at, closes: issue }
+}
+
+const DEFAULT_PORTS: PrimePorts = {
+	pull: read_source,
+	closing: read_closing_source,
+	ledger_path: lane_ledger.target,
+}
+
+// The ledger's merges, read on each judgement so a merge recorded since the prime counts; an absent
+// ledger records none.
+function merges_of(path: string | undefined): () => ReadonlyArray<MergeSample> {
+	return function merges(): ReadonlyArray<MergeSample> {
+		if (path === undefined) return []
+
+		return lane_ledger
+			.read_entries(path)
+			.filter((entry): entry is MergeEntry => entry.kind === lane_ledger.KIND.MERGE)
+	}
+}
+
+// A failed read stays unread, so the next prime asks again.
+async function remember(condition: Condition, ports: PrimePorts): Promise<void> {
+	const read = condition.via === 'pull' ? ports.pull : ports.closing
+
+	try {
+		issue_sample_gate.record(condition, await read(condition.cited))
+	} catch {
+		issue_sample_gate.record(condition, undefined)
+	}
+}
+
+// Reads ahead what the bodies' conditions need. Nothing is read for bodies that declare none.
+async function prime(
+	bodies: ReadonlyArray<string | undefined>,
+	ports: PrimePorts = DEFAULT_PORTS,
+): Promise<void> {
+	const unread = issue_sample_gate.unread_of(bodies)
+
+	if (unread.length === 0) return
+
+	issue_sample_gate.use_merges(merges_of(await ports.ledger_path()))
+	await Promise.all(
+		unread.map(async (condition) => {
+			await remember(condition, ports)
+		}),
+	)
+}
+
+const issue_sample_prime = {
+	prime,
+	read_closing: read_closing_source,
+	read_source,
+}
+
+export type { PrimePorts }
+export { issue_sample_prime }

package/scripts/issue/issue-sample-required.ts

@@ -0,0 +1,57 @@
+import { acceptance_map } from '#scripts/review/acceptance-map'
+import { issue_sample_gate } from './issue-sample-gate'
+import { measure_declaration } from './measure-declaration'
+import { size_estimate } from './size-estimate'
+
+// joshuafolkken/kit#4901: a follow-up that measures a pull request's effect reads records that only
+// the merges after it write. Filed without its start condition, the backlog offers it at once and the
+// lane finds no sample (#4897). It is refused until it declares the condition (`measurement.md`).
+//
+// A measurement follow-up is a body carrying a measure declaration, or one changing no file whose criterion
+// reads the period after a cited change: its wording says "after #N" whichever record it reads
+// (#5103), or it names a reader of the post-merge records. A record read that cites nothing (a CI
+// investigation) waits on no merge, so it files as before. A bare "after" character ends many words
+// that are no period ("last", "around", "from now on"), so it counts only right after the citation,
+// a possessive particle or "merge"; one opening a word ("see below", "cleanup", "successor") is no
+// period either.
+
+const AFTER_CITED_CHANGE: ReadonlyArray<RegExp> = [
+	/#[1-9]\d*(?:\s*|[^#\n]{0,16}?(?:の|マージ(?:した|直)?))後(?![述始片続])/u,
+	/#[1-9]\d*[^#\n]{0,16}?(?:以降|以後)/u,
+]
+const RECORD_READERS: ReadonlyArray<string> = ['lane:stats', 'actions/runs', 'ship --log']
+const CITATION_PATTERN = /#[1-9]\d*/u
+const MISSING = `measurement follow-up without its start condition: declare \`${issue_sample_gate.DECLARATION}\`, or \`${issue_sample_gate.CLOSING_FORMAT}\` before that pull request exists, under ## 背景 — prompts/collaboration-workflow/measurement.md → "効果を測る後続 Issue"`
+// joshuafolkken/kit#5144: one waiting K merges reads one value against a bound, which `backlog:drive`
+// does without a lane once it is declared; the declaration is the default, a stated reason the exception.
+const UNDECLARED = `measurement follow-up without a measure declaration: declare \`${measure_declaration.DECLARATION}\` (any \`lane:stats\` cell: \`pnpm josh lane:value cell\`), or \`${measure_declaration.ABSENT}\` when no one command prints the value, under ## 背景 — prompts/collaboration-workflow/measurement.md → "効果を測る後続 Issue"\n${measure_declaration.EXAMPLE}`
+
+function measures_a_change(criterion: string): boolean {
+	if (AFTER_CITED_CHANGE.some((pattern) => pattern.test(criterion))) return true
+
+	return (
+		CITATION_PATTERN.test(criterion) && RECORD_READERS.some((reader) => criterion.includes(reader))
+	)
+}
+
+function is_measurement(body: string): boolean {
+	if (measure_declaration.parse(body) !== undefined) return true
+	if (size_estimate.declared_files(body) !== 0) return false
+
+	return acceptance_map.criteria_of(body).some((criterion) => measures_a_change(criterion.text))
+}
+
+// The refusal for a measurement follow-up whose start condition does not parse — missing, or
+// malformed beside `issue_sample_gate.problems`' format refusal — or whose condition parses with no
+// measure declaration nor a reason for none; `undefined` for any other filing.
+function problem(body: string): string | undefined {
+	if (issue_sample_gate.cited_number(body) !== undefined) {
+		return measure_declaration.is_stated(body) ? undefined : UNDECLARED
+	}
+
+	return is_measurement(body) ? MISSING : undefined
+}
+
+const issue_sample_required = { problem }
+
+export { issue_sample_required }

package/scripts/issue/issue-sample-source.ts

@@ -15,7 +15,7 @@ import { session_cite } from './session-cite'
 
 interface SourcePorts {
 	is_pull: (number: number, repo: string | undefined) => Promise<boolean | undefined>
-	closing_pr: (issue: number) => Promise<string | undefined>
+	closing_pr: (issue: number) => Promise<number | undefined>
 }
 
 async function read_is_pull(
@@ -33,15 +33,14 @@ async function read_is_pull(
 	}
 }
 
-// The closing pull request's number, read off the URL `read_closing_pr` answers.
-async function read_closing_pr(issue: number): Promise<string | undefined> {
-	const url = await issue_closing_pr.read_closing_pr(String(issue))
-
-	return url?.slice(url.lastIndexOf('/') + 1)
+async function read_closing_number(issue: number): Promise<number | undefined> {
+	return await issue_closing_pr.read_closing_number(issue)
 }
 
-const DEFAULT_PORTS: SourcePorts = { is_pull: read_is_pull, closing_pr: read_closing_pr }
+const DEFAULT_PORTS: SourcePorts = { is_pull: read_is_pull, closing_pr: read_closing_number }
 
+// No merged closing pull request yet — the lane filing ahead of its own (joshuafolkken/kit#5051) —
+// points at the form that waits on the pull request to come.
 async function hint_of(
 	issue: number,
 	repo: string | undefined,
@@ -49,19 +48,21 @@ async function hint_of(
 ): Promise<string> {
 	const closing = repo === undefined ? await ports.closing_pr(issue) : undefined
 
-	if (closing === undefined) return 'cite the pull request whose merge it waits on'
+	if (closing === undefined) {
+		return `cite the pull request whose merge it waits on, or write \`${issue_sample_gate.CLOSING_FORMAT}\` to wait on the one that closes it`
+	}
 
 	return `cite the pull request that closed it: ${session_cite.issue(closing)}`
 }
 
-// The refusal for a condition citing an issue, or `undefined` when it cites a pull request, cites
-// nothing, or cannot be read.
+// The refusal for a pull request condition citing an issue, or `undefined` when it cites a pull
+// request, cites nothing, uses the issue form, or cannot be read.
 async function problem(
 	body: string,
 	repo?: string,
 	ports: SourcePorts = DEFAULT_PORTS,
 ): Promise<string | undefined> {
-	const number = issue_sample_gate.cited_number(body)
+	const number = issue_sample_gate.cited_via(body, 'pull')
 
 	if (number === undefined || (await ports.is_pull(number, repo)) !== false) return undefined
 	const cited = session_cite.issue(number, undefined, repo)

package/scripts/issue/issue-search.ts

@@ -0,0 +1,124 @@
+import { git_gh_exec } from '#scripts/gh/git-gh-exec'
+import { issue_label_schema } from '#scripts/git/git-schemas'
+import { parse_json } from '#scripts/git/parse-json-array'
+import { bounded_pool } from '#scripts/lib/bounded-pool'
+import { z } from 'zod'
+
+// Every issue one `search/issues` query matches, read page by page. `defect:rate`'s windows and
+// `effect:audit`'s listing ask it.
+
+const PER_PAGE = '100'
+const FIRST_PAGE = 1
+const SECOND_PAGE = 2
+// The search API serves at most this many results, so a window past it holds no further page.
+const SEARCH_RESULT_CEILING = 1000
+// The search API allows 30 requests a minute, so this bounds only how many are in flight at once.
+const PAGE_CONCURRENCY = 4
+
+const search_item_schema = z.object({
+	number: z.number().optional(),
+	title: z.string().optional(),
+	state: z.string().optional(),
+	body: z.string().nullish(),
+	labels: z.array(issue_label_schema),
+})
+
+// One page of `search/issues`.
+const search_page_schema = z.object({
+	total_count: z.number(),
+	incomplete_results: z.boolean(),
+	items: z.array(search_item_schema),
+})
+
+type SearchPage = z.infer<typeof search_page_schema>
+
+interface SearchIssue {
+	number: number
+	title: string
+	state: string
+	body: string
+	labels: ReadonlyArray<string>
+}
+
+interface SearchResult {
+	issues: ReadonlyArray<SearchIssue>
+	is_capped: boolean
+}
+
+function search_path(query: string, page: number = FIRST_PAGE): string {
+	const parameters = new URLSearchParams({ q: query, per_page: PER_PAGE })
+
+	if (page !== FIRST_PAGE) parameters.set('page', String(page))
+
+	return `search/issues?${parameters.toString()}`
+}
+
+// How many pages the search holds, read off the first page's own count. Bounded by the API's
+// ceiling, past which GitHub serves no page at all — so this asks for exactly the pages `gh api
+// --paginate` would walk to.
+function page_count(first: SearchPage): number {
+	return Math.ceil(Math.min(first.total_count, SEARCH_RESULT_CEILING) / Number(PER_PAGE))
+}
+
+async function read_page(query: string, page: number): Promise<SearchPage | undefined> {
+	const raw = await git_gh_exec.exec_gh_api({ path: search_path(query, page) })
+
+	return parse_json.parse_json_object_or_undefined(raw, search_page_schema)
+}
+
+// Every page of one search. Not `gh api --paginate`: it follows each page's `next` link one page
+// after another, at about 1.5 s a page. The first page names the total, so the rest are fetched
+// together; any page that does not read fails the whole search.
+async function read_pages(query: string): Promise<ReadonlyArray<SearchPage> | undefined> {
+	const first = await read_page(query, FIRST_PAGE)
+
+	if (first === undefined) return undefined
+
+	const rest_numbers = Array.from(
+		{ length: Math.max(page_count(first) - FIRST_PAGE, 0) },
+		(_value, index) => index + SECOND_PAGE,
+	)
+	const rest = await bounded_pool.bounded_map(
+		rest_numbers,
+		PAGE_CONCURRENCY,
+		async (page) => await read_page(query, page),
+	)
+
+	return rest.every((page) => page !== undefined) ? [first, ...rest] : undefined
+}
+
+function to_issue(item: z.infer<typeof search_item_schema>): SearchIssue {
+	return {
+		number: item.number ?? 0,
+		title: item.title ?? '',
+		state: item.state ?? '',
+		body: item.body ?? '',
+		labels: item.labels.map((label) => label.name),
+	}
+}
+
+function to_result(pages: ReadonlyArray<SearchPage>): SearchResult {
+	const issues = pages.flatMap((page) => page.items.map((item) => to_issue(item)))
+	// The search API serves at most 1000 results, and says so only by a total larger than what it
+	// handed back — a window past that ceiling is measured on part of itself.
+	const total = pages[0]?.total_count ?? 0
+	const is_incomplete = pages.some((page) => page.incomplete_results)
+
+	return { issues, is_capped: is_incomplete || total > issues.length }
+}
+
+// The search's issues, or `undefined` when any page could not be read.
+async function search(query: string): Promise<SearchResult | undefined> {
+	try {
+		const pages = await read_pages(query)
+
+		return pages === undefined ? undefined : to_result(pages)
+	} catch {
+		return undefined
+	}
+}
+
+const issue_search = { search, search_path }
+
+export type { SearchIssue, SearchResult }
+export { issue_search }

package/scripts/issue/issue-state.ts

@@ -1,6 +1,12 @@
 import { parse_json_object_or_undefined } from '#scripts/git/parse-json-array'
 import { z } from 'zod'
-import { has_any_label, NEEDS_HUMAN_REVIEW_LABEL } from './issue-labels'
+import {
+	has_any_label,
+	has_label_name,
+	NEEDS_HUMAN_REVIEW_LABEL,
+	PLANNED_LABEL,
+} from './issue-labels'
+import type { StateRead } from './issue-state-cli'
 
 // The answer `josh issue:state` prints, kept apart from the reading and the printing so the shape of
 // the report is decided by one pure function.
@@ -93,7 +99,13 @@ function format_attributed_issue_state(issue_number: string, state: IssueState):
 	return `${ISSUE_LABEL}${issue_number}\n${format_issue_state(state)}`
 }
 
+// Whether a read issue carries `run:planned` — asked by `run:stage` and by `run:entry`'s trust gate.
+function is_planned(read: StateRead): boolean {
+	return read.kind === 'state' && has_label_name(read.state.labels, PLANNED_LABEL)
+}
+
 const issue_state = {
+	is_planned,
 	NO_LABELS,
 	parse_issue_state,
 	format_issue_state,