@joshuafolkken/kit 1.1514.0 → 1.2114.0

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

@@ -0,0 +1,77 @@
+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 { issue_closing_pr } from './issue-closing-pr'
+import { issue_sample_gate } from './issue-sample-gate'
+import { session_cite } from './session-cite'
+
+// joshuafolkken/kit#4460: the start condition cites the pull request whose merge it waits on. An issue
+// number passes the format check, then reads as a pull request that is never found, so the issue waits
+// forever. The filing reads what the number names and refuses an issue, citing the merged pull request
+// that closed it when there is one. An unreadable number passes — an outage is no reason to stop.
+//
+// `repo` is the filing's target, `undefined` for this checkout. The closing pull request is looked up
+// only here: `issue_closing_pr` reads this checkout's timeline, so a foreign target gets the plain hint.
+
+interface SourcePorts {
+	is_pull: (number: number, repo: string | undefined) => Promise<boolean | undefined>
+	closing_pr: (issue: number) => Promise<number | undefined>
+}
+
+async function read_is_pull(
+	number: number,
+	repo: string | undefined,
+): Promise<boolean | undefined> {
+	try {
+		const json = await git_gh_exec.exec_gh_api({
+			path: git_gh_api_path.issue_api_path(String(number), repo),
+		})
+
+		return git_gh_issue_rest.is_pull_request(git_gh_issue_rest.parse_rest_issue(json))
+	} catch {
+		return undefined
+	}
+}
+
+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_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,
+	ports: SourcePorts,
+): 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, 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 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_via(body, 'pull')
+
+	if (number === undefined || (await ports.is_pull(number, repo)) !== false) return undefined
+	const cited = session_cite.issue(number, undefined, repo)
+	const hint = await hint_of(number, repo, ports)
+
+	return `\`- 実施可能条件:\` cites ${cited}, an issue, not a pull request — ${hint}`
+}
+
+const issue_sample_source = { problem }
+
+export type { SourcePorts }
+export { issue_sample_source }

package/scripts/issue/issue-scout-cli.ts

@@ -1,6 +1,4 @@
-#!/usr/bin/env tsx
 import { readFile } from 'node:fs/promises'
-import { fileURLToPath } from 'node:url'
 import { epic_audit_logic } from '#scripts/epic/epic-audit'
 import { epic_bundle, type BacklogIssue, type BundleDecision } from '#scripts/epic/epic-bundle'
 import { epic_bundle_cli } from '#scripts/epic/epic-bundle-cli'
@@ -34,7 +32,6 @@ const { CLOSED_CEILING_LINE, CLOSED_UNREADABLE_LINE, read_recently_closed, warn_
 
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
-const ARGV_OFFSET = 2
 const SCORE_DIGITS = 2
 const USAGE = 'Usage: josh issue:scout "<title>" [--body "<draft>" | --body-file <path>]'
 const UNKNOWN_REPO_MESSAGE =
@@ -394,12 +391,6 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 	return await report(args, repo)
 }
 
-// `process.exitCode` rather than `process.exit()`: the answer goes to standard output and a write to
-// a pipe is asynchronous on macOS, so exiting can tear the process down before it drains.
-async function main(argv: ReadonlyArray<string>): Promise<void> {
-	process.exitCode = await run(argv)
-}
-
 const issue_scout_cli = {
 	USAGE,
 	UNKNOWN_REPO_MESSAGE,
@@ -415,7 +406,5 @@ const issue_scout_cli = {
 	run,
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
-
 export type { ScoutArguments, ScoutOutcome }
 export { issue_scout_cli }

package/scripts/issue/issue-scout-main.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { issue_scout_cli } from './issue-scout-cli'
+
+// The `josh issue:scout` entry, kept apart from `issue-scout-cli.ts` because other modules import
+// that one: a bundle is one file, so a main guard there would fire for every command that carries it
+// (joshuafolkken/kit#4186). `process.exitCode` rather than `process.exit()`: the answer goes to
+// standard output and a write to a pipe is asynchronous on macOS, so exiting can tear the process
+// down before it drains.
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const ARGV_OFFSET = 2
+
+	process.exitCode = await issue_scout_cli.run(process.argv.slice(ARGV_OFFSET))
+}

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-cli.ts

@@ -1,5 +1,3 @@
-#!/usr/bin/env tsx
-import { fileURLToPath } from 'node:url'
 import { git_gh_command } from '#scripts/gh/git-gh-command'
 import type { IssueReadReason } from '#scripts/gh/git-gh-issue-read'
 import { issue_number_shape } from '#scripts/issue/issue-number-shape'
@@ -29,7 +27,6 @@ import { issue_state, type IssueState } from './issue-state'
 // are told apart here and neither is a state.
 
 const FAILURE_EXIT_CODE = 1
-const ARGV_OFFSET = 2
 const USAGE = 'Usage: josh issue:state <issue-number> [<issue-number> ...] [--repo <owner/repo>]'
 // A blank line between the blocks of a multi-number report, so a person sees where one issue ends
 // while a reader matching `issue: ` still finds each block by its first line.
@@ -172,21 +169,14 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 	return issue_report_failures.report_failures(reports, FAILURE_TERMS)
 }
 
-async function main(argv: ReadonlyArray<string>): Promise<void> {
-	process.exitCode = await run(argv)
-}
-
 const issue_state_cli = {
 	READ_CONCURRENCY,
 	STATE_FIELDS,
 	USAGE,
-	main,
 	parse_request,
 	read_issue,
 	run,
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
-
 export type { StateRead }
 export { issue_state_cli }

package/scripts/issue/issue-state-main.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { issue_state_cli } from './issue-state-cli'
+
+// The `josh issue:state` entry, kept apart from `issue-state-cli.ts` because other modules import
+// that one: a bundle is one file, so a main guard there would fire for every command that carries it
+// (joshuafolkken/kit#4186).
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const ARGV_OFFSET = 2
+
+	process.exitCode = await issue_state_cli.run(process.argv.slice(ARGV_OFFSET))
+}

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,

package/scripts/issue/issue-template-section.ts

@@ -0,0 +1,43 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { package_path } from '#scripts/init/init-paths'
+import { markdown_section } from './markdown-section'
+
+// One section of the Issue body template, cut from the fenced template in `issue-template.md` — its
+// single source — so a refusal for a missing heading can print the section to paste back in rather than
+// sending the filer to reopen the document (joshuafolkken/kit#5206).
+const TEMPLATE_PATH = 'prompts/collaboration-workflow/issue-template.md'
+const TEMPLATE_FENCE = '````'
+
+// The lines inside the document's four-backtick template fence; an empty array when it has none.
+function template_lines(document: string): ReadonlyArray<string> {
+	const lines = markdown_section.lines_of(document)
+	const start = lines.findIndex((line) => line.startsWith(TEMPLATE_FENCE))
+	const end = lines.findIndex((line, index) => index > start && line.trim() === TEMPLATE_FENCE)
+
+	if (start === -1 || end === -1) return []
+
+	return lines.slice(start + 1, end)
+}
+
+// The heading and its template lines, trailing blank lines dropped; `undefined` when the template has no
+// such section.
+function section_of(document: string, heading: string): string | undefined {
+	const template = template_lines(document).join('\n')
+
+	if (!markdown_section.has_line(template, heading)) return undefined
+
+	return [heading, ...markdown_section.section_lines(template, heading)].join('\n').trimEnd()
+}
+
+// A package without the template prints the bare problem rather than failing the lint.
+function section(heading: string): string | undefined {
+	const template_path = package_path(TEMPLATE_PATH)
+
+	if (!existsSync(template_path)) return undefined
+
+	return section_of(readFileSync(template_path, 'utf8'), heading)
+}
+
+const issue_template_section = { section, section_of }
+
+export { issue_template_section }

package/scripts/issue/issue-watch-diff.ts

@@ -1,9 +1,11 @@
+import { gh_author_association } from '#scripts/gh/gh-author-association'
 import { read_json_listing } from '#scripts/git/parse-json-array'
 import { z } from 'zod'
 
-// What a person changed on an issue since a run last read it, as the one pure answer the hook, the
-// review attestation, `josh issue:ack` and `josh followup` all print. Kept free of I/O so the four
-// callers cannot each draw the line between "a person's update" and "noise" differently.
+// What a person changed on an issue since a run last read it, as the one answer the hook, the review
+// attestation, `josh issue:ack` and `josh followup` all print. Kept in one place so the four callers
+// cannot each draw the line between "a person's update" and "noise" differently; its only I/O is the
+// write-access lookup `gh_author_association` makes for a `MEMBER` / `COLLABORATOR`.
 //
 // **A person's update is a body edit or a comment nobody automated.** A bot's comment (`type: Bot`,
 // or a `[bot]` login) is not one. A run's own comment is posted under the person's own `gh` login,
@@ -12,6 +14,19 @@ import { z } from 'zod'
 // through a raw `gh api` counts as a person's — the direction that costs one `josh issue:ack`, never a
 // missed correction.
 //
+// **Only an author with write access is a person here** (`gh_author_association`). On a public
+// repository anyone can comment, so a comment from anyone else is never handed to a run as an update,
+// and its `RUN_MARKER` is not taken as josh's own. A `MEMBER` / `COLLABORATOR` whose lookup failed
+// (`is_trusted: undefined` — the hook's timeout fired) is neither: their comment is announced with its
+// body withheld, costing one `josh issue:ack` rather than a missed correction, and its marker is not
+// trusted.
+//
+// **A body edit is a person's update only when the issue's author has write access.** GitHub does not
+// say who edited a body, and its author can always edit it, so a body under an author without write
+// access is never handed to a run as an update: its edit becomes a notice with the text withheld,
+// which asks for nothing and holds no merge. A `MEMBER` / `COLLABORATOR` author whose lookup failed
+// is treated like their comment: the edit is announced with its text withheld and stays pending.
+//
 // **Comment edits are out of scope.** A new comment carries an id above the baseline's; an edited
 // one keeps its id and is not seen. The body is compared whole, so its edits are.
 
@@ -21,6 +36,10 @@ const BOT_SUFFIX = '[bot]'
 const NO_COMMENT_ID = 0
 const UNKNOWN_AUTHOR = '(unknown)'
 const UNKNOWN_TIME = '(undated)'
+const UNVERIFIED_BODY =
+	"(body withheld — the author's write access could not be checked; read it with `josh issue:read`)"
+
+const WITHHELD_BODY_EDIT = `The body of this run's issue was edited, but its author is not ${gh_author_association.TRUSTED_LIST}, so the edit is withheld: it is not an instruction to this run and holds nothing — carry on.`
 
 const BODY_HEADING = 'Body edited:'
 const REMOVED_PREFIX = '- '
@@ -36,11 +55,14 @@ const comment_schema = z.looseObject({
 	user: z.looseObject({ login: z.string(), type: z.string().optional() }).nullish(),
 	created_at: z.string().optional(),
 	body: z.string().nullish(),
+	author_association: z.string().nullish(),
 })
 
 interface WatchComment {
 	id: number
 	author: string
+	// `undefined` when the write-access lookup failed.
+	is_trusted: boolean | undefined
 	is_automated: boolean
 	created_at: string
 	body: string
@@ -48,6 +70,8 @@ interface WatchComment {
 
 interface WatchSnapshot {
 	body: string
+	// Whether the issue's author has write access — `undefined` when the lookup failed.
+	is_body_trusted: boolean | undefined
 	comments: ReadonlyArray<WatchComment>
 }
 
@@ -60,26 +84,48 @@ function is_bot(user: z.infer<typeof comment_schema>['user']): boolean {
 	return user?.type === BOT_TYPE || (user?.login.endsWith(BOT_SUFFIX) ?? false)
 }
 
-function is_automated(user: z.infer<typeof comment_schema>['user'], body: string): boolean {
-	return is_bot(user) || body.includes(RUN_MARKER)
+function is_automated(
+	raw: z.infer<typeof comment_schema>,
+	is_trusted: boolean | undefined,
+): boolean {
+	return is_bot(raw.user) || (is_trusted === true && (raw.body?.includes(RUN_MARKER) ?? false))
 }
 
-function to_comment(raw: z.infer<typeof comment_schema>): WatchComment {
-	const body = raw.body ?? ''
-	const author = raw.user?.login ?? UNKNOWN_AUTHOR
-	const created_at = raw.created_at ?? UNKNOWN_TIME
+async function to_comment(
+	raw: z.infer<typeof comment_schema>,
+	timeout_ms?: number,
+): Promise<WatchComment> {
+	const login = raw.user?.login
+	const is_trusted = await gh_author_association.trust_of({
+		login,
+		association: raw.author_association,
+		timeout_ms,
+	})
 
-	return { id: raw.id, author, is_automated: is_automated(raw.user, body), created_at, body }
+	return {
+		id: raw.id,
+		author: login ?? UNKNOWN_AUTHOR,
+		is_trusted,
+		is_automated: is_automated(raw, is_trusted),
+		created_at: raw.created_at ?? UNKNOWN_TIME,
+		body: raw.body ?? '',
+	}
 }
 
 // `undefined` — never `[]` — for a listing that could not be read, so a failed read is never taken
-// for "nobody commented".
-function parse_comments(json: string | undefined): ReadonlyArray<WatchComment> | undefined {
+// for "nobody commented". `timeout_ms` bounds each write-access lookup, which run concurrently, so a
+// hook's read stays inside its own timeout.
+async function parse_comments(
+	json: string | undefined,
+	timeout_ms?: number,
+): Promise<ReadonlyArray<WatchComment> | undefined> {
 	if (json === undefined) return undefined
 
 	const listing = read_json_listing(json, comment_schema)
 
-	return listing.kind === 'read' ? listing.rows.map((row) => to_comment(row)) : undefined
+	if (listing.kind !== 'read') return undefined
+
+	return await Promise.all(listing.rows.map(async (row) => await to_comment(row, timeout_ms)))
 }
 
 function last_comment_id(comments: ReadonlyArray<WatchComment>): number {
@@ -118,7 +164,9 @@ function body_section(previous_raw: string, current_raw: string): string | undef
 }
 
 function comment_section(comment: WatchComment): string {
-	return `${COMMENT_HEADING}${comment.author}${AT}${comment.created_at}${LINE_SEPARATOR}${comment.body}`
+	const body = comment.is_trusted === true ? comment.body : UNVERIFIED_BODY
+
+	return `${COMMENT_HEADING}${comment.author}${AT}${comment.created_at}${LINE_SEPARATOR}${body}`
 }
 
 function new_person_comments(
@@ -126,13 +174,27 @@ function new_person_comments(
 	snapshot: WatchSnapshot,
 ): ReadonlyArray<WatchComment> {
 	return snapshot.comments.filter(
-		(comment) => comment.id > baseline.last_comment_id && !comment.is_automated,
+		(comment) =>
+			comment.id > baseline.last_comment_id &&
+			comment.is_trusted !== false &&
+			!comment.is_automated,
 	)
 }
 
+function is_body_edited(baseline: WatchBaseline, snapshot: WatchSnapshot): boolean {
+	return to_lf(baseline.body) !== to_lf(snapshot.body)
+}
+
+function unread_body(baseline: WatchBaseline, snapshot: WatchSnapshot): string | undefined {
+	if (snapshot.is_body_trusted === true) return body_section(baseline.body, snapshot.body)
+	if (snapshot.is_body_trusted === false || !is_body_edited(baseline, snapshot)) return undefined
+
+	return `${BODY_HEADING}${LINE_SEPARATOR}${UNVERIFIED_BODY}`
+}
+
 // The unread update as the text a run is shown, or `undefined` when a person changed nothing.
 function unread_diff(baseline: WatchBaseline, snapshot: WatchSnapshot): string | undefined {
-	const body = body_section(baseline.body, snapshot.body)
+	const body = unread_body(baseline, snapshot)
 	const comments = new_person_comments(baseline, snapshot).map((comment) =>
 		comment_section(comment),
 	)
@@ -141,11 +203,20 @@ function unread_diff(baseline: WatchBaseline, snapshot: WatchSnapshot): string |
 	return sections.length === 0 ? undefined : sections.join(SECTION_SEPARATOR)
 }
 
+// The notice for a body edit `unread_diff` withholds, or `undefined` when there is none.
+function withheld_notice(baseline: WatchBaseline, snapshot: WatchSnapshot): string | undefined {
+	if (snapshot.is_body_trusted !== false || !is_body_edited(baseline, snapshot)) return undefined
+
+	return WITHHELD_BODY_EDIT
+}
+
 const issue_watch_diff = {
 	RUN_MARKER,
+	WITHHELD_BODY_EDIT,
 	baseline_of,
 	parse_comments,
 	unread_diff,
+	withheld_notice,
 }
 
 export type { WatchBaseline, WatchComment, WatchSnapshot }

package/scripts/issue/issue-watch-hook.ts

@@ -22,7 +22,16 @@ const POLL_INTERVAL_MS = 180_000
 const POLL_TIMEOUT_MS = 5000
 
 function is_new_to_run(record: WatchRecord | undefined): record is WatchRecord {
-	return record?.pending !== undefined && record.pending !== record.shown
+	const news = record === undefined ? undefined : issue_watch.news_of(record)
+
+	return news !== undefined && news !== record?.shown
+}
+
+// A withheld body edit is shown as its own notice: it asks for no `josh issue:ack`.
+function message_of(record: WatchRecord): string {
+	return record.pending === undefined
+		? (record.notice ?? '')
+		: issue_watch_gate.unread_message(record)
 }
 
 async function new_update_reason(now: Date): Promise<string | undefined> {
@@ -36,7 +45,7 @@ async function new_update_reason(now: Date): Promise<string | undefined> {
 
 	issue_watch.mark_shown(record)
 
-	return issue_watch_gate.unread_message(record)
+	return message_of(record)
 }
 
 async function watch_reason(now: Date = new Date()): Promise<string | undefined> {