@joshuafolkken/kit 1.1387.0 → 1.1453.0

package/scripts/agent/claude-agent-argv.ts

@@ -8,7 +8,19 @@ import {
 } from './agent-role-profile'
 
 const AGENT_COMMAND = 'claude'
-const AGENT_FLAGS: ReadonlyArray<string> = ['-p', '--verbose', '--output-format', 'stream-json']
+// **The permission mode is passed, not left to the checkout's `.claude/settings.json`.** Claude Code
+// ignores a project's `defaultMode: bypassPermissions` (since v2.1.257) and its `permissions.allow` in
+// a workspace whose trust dialog was never accepted — every fresh clone and every new lane worktree — so
+// a headless child stopped on approvals nobody could give. The flag sets the mode that file declares;
+// its `deny` list stays in effect (#3796).
+const PERMISSION_FLAGS: ReadonlyArray<string> = ['--permission-mode', 'bypassPermissions']
+const AGENT_FLAGS: ReadonlyArray<string> = [
+	'-p',
+	'--verbose',
+	'--output-format',
+	'stream-json',
+	...PERMISSION_FLAGS,
+]
 const MODEL_FLAG = '--model'
 const EFFORT_FLAG = '--effort'
 // Resumes a stored session by id. An `outage` re-dispatch passes the

package/scripts/auth/auth-setup-cli.ts

@@ -0,0 +1,101 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { parseArgs } from 'node:util'
+import { execa } from 'execa'
+import { claude_token } from './claude-token'
+import { claude_token_output } from './claude-token-output'
+
+// `josh auth:setup` — run `claude setup-token` and keep the token it prints in the macOS keychain,
+// where `josh fresh:run` reads it. The token reaches neither the screen nor a file: it is replaced in
+// the command's output. `--check` answers whether one is saved.
+
+const ARGV_OFFSET = 2
+const FAILURE_EXIT_CODE = 1
+const CLAUDE = 'claude'
+const SAVED = `saved: ${claude_token.VARIABLE} (macOS keychain)`
+const NO_TOKEN = 'claude setup-token printed no token, so nothing was saved.'
+const NO_KEYCHAIN = `This machine has no macOS keychain, so nothing was run. Run \`claude setup-token\` yourself and export ${claude_token.VARIABLE} — josh fresh:run reads it when the keychain has none.`
+const NOT_SAVED = 'The keychain did not keep the token. Run `pnpm josh auth:setup` again.'
+
+interface Printed {
+	decoder: TextDecoder
+	text: string
+	shown: number
+}
+
+function refuse(message: string): number {
+	console.error(message)
+
+	return FAILURE_EXIT_CODE
+}
+
+function check(): number {
+	const date = claude_token.saved_date()
+
+	if (date === undefined) {
+		return refuse(`missing: no ${claude_token.VARIABLE} saved. ${claude_token.SETUP_HINT}`)
+	}
+
+	console.info(`ok: ${claude_token.VARIABLE} saved on ${date} (macOS keychain)`)
+
+	return 0
+}
+
+function store(token: string | undefined): number {
+	if (token === undefined) return refuse(NO_TOKEN)
+
+	if (!claude_token.save(token)) return refuse(NOT_SAVED)
+
+	console.info(SAVED)
+
+	return 0
+}
+
+// The sign-in URL and any prompt are shown as they arrive; from the token on, the output is held
+// back and shown once claude ends, with the token replaced.
+function show_live(printed: Printed, chunk: Uint8Array): void {
+	printed.text += printed.decoder.decode(chunk, { stream: true })
+	const live = claude_token_output.live_length(printed.text)
+
+	process.stdout.write(printed.text.slice(printed.shown, live))
+	printed.shown = live
+}
+
+// The browser sign-in needs the terminal's stdin, so only stdout passes through josh.
+async function setup(): Promise<number> {
+	if (!claude_token.has_keychain()) return refuse(NO_KEYCHAIN)
+
+	const printed: Printed = { decoder: new TextDecoder(), text: '', shown: 0 }
+	const child = execa(CLAUDE, ['setup-token'], {
+		stdin: 'inherit',
+		stderr: 'inherit',
+		reject: false,
+	})
+
+	child.stdout.on('data', (chunk: Uint8Array) => {
+		show_live(printed, chunk)
+	})
+	const result = await child
+	const held = printed.text.slice(printed.shown) + printed.decoder.decode()
+	const { token, shown } = claude_token_output.capture(held)
+
+	process.stdout.write(shown)
+
+	if (result.failed) return refuse(`claude setup-token failed: ${result.shortMessage ?? CLAUDE}`)
+
+	return store(token)
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const { values } = parseArgs({ args: [...argv], options: { check: { type: 'boolean' } } })
+
+	return values.check === true ? check() : await setup()
+}
+
+const auth_setup_cli = { run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	process.exitCode = await run(process.argv.slice(ARGV_OFFSET))
+}
+
+export { auth_setup_cli }

package/scripts/auth/claude-token-output.ts

@@ -0,0 +1,78 @@
+import { stripVTControlCharacters } from 'node:util'
+
+// What `claude setup-token` printed, split into the token and the text that may be shown: the token
+// is replaced, so it reaches neither the screen nor a log.
+
+const REDACTED = '[REDACTED]'
+const TOKEN_START = 'sk-ant-oat'
+const TOKEN_PATTERN = /sk-ant-oat\d+-[\w-]+/u
+const EVERY_TOKEN_PATTERN = new RegExp(TOKEN_PATTERN.source, 'gu')
+// A narrow terminal wraps the token onto lines of its own characters alone, so a continuation is a
+// whole such line and the prose after the token never joins it.
+const CONTINUATION_PATTERN = /^[\w-]+$/u
+const LINE_BREAK_PATTERN = /\r?\n/u
+
+interface Captured {
+	token: string | undefined
+	shown: string
+}
+
+// A line that starts a token is another copy of it, never the tail of the one before.
+function is_continuation(line: string): boolean {
+	return CONTINUATION_PATTERN.test(line) && !line.startsWith(TOKEN_START)
+}
+
+function continuation(lines: ReadonlyArray<string>): Array<string> {
+	const length = lines.findIndex((line) => !is_continuation(line.trim()))
+
+	return (length === -1 ? lines : lines.slice(0, length)).map((line) => line.trim())
+}
+
+// Every copy of the token is replaced, its wrapped tail with it: Ink may draw it in more than one frame.
+function redact(lines: ReadonlyArray<string>): Array<string> {
+	const start = lines.findIndex((line) => TOKEN_PATTERN.test(line))
+
+	if (start === -1) return [...lines]
+
+	const [head = '', ...rest] = lines.slice(start)
+	const remaining = rest.slice(continuation(rest).length)
+
+	return [
+		...lines.slice(0, start),
+		head.replaceAll(EVERY_TOKEN_PATTERN, () => REDACTED),
+		...redact(remaining),
+	]
+}
+
+function capture(output: string): Captured {
+	const lines = stripVTControlCharacters(output).split(LINE_BREAK_PATTERN)
+	const start = lines.findIndex((line) => TOKEN_PATTERN.test(line))
+	const head = lines[start]
+	const shown = redact(lines).join('\n')
+
+	if (head === undefined) return { token: undefined, shown }
+
+	const token = [TOKEN_PATTERN.exec(head)?.[0], ...continuation(lines.slice(start + 1))].join('')
+
+	return { token, shown }
+}
+
+// How much of the output so far may be shown as it arrives — the sign-in URL and any prompt come
+// before the token: everything before the token, less a tail that could be the start of one.
+function live_length(output: string): number {
+	const start = output.indexOf(TOKEN_START)
+
+	if (start !== -1) return start
+
+	const prefixes = Array.from({ length: TOKEN_START.length }, (_, index) =>
+		TOKEN_START.slice(0, index + 1),
+	)
+	const held = prefixes.findLast((prefix) => output.endsWith(prefix))
+
+	return output.length - (held?.length ?? 0)
+}
+
+const claude_token_output = { capture, live_length }
+
+export { claude_token_output }
+export type { Captured }

package/scripts/auth/claude-token.ts

@@ -0,0 +1,68 @@
+import { execaSync } from 'execa'
+
+// Where the Claude Code token of `josh fresh:run` lives on the host: the macOS keychain item
+// `josh auth:setup` writes, or — on a machine without a keychain — `CLAUDE_CODE_OAUTH_TOKEN` in the
+// environment. No shell profile is read or written, so no other Claude Code on the host changes how
+// it signs in.
+
+const VARIABLE = 'CLAUDE_CODE_OAUTH_TOKEN'
+const SERVICE = 'josh-claude-code-oauth-token'
+const ACCOUNT = 'josh'
+const SECURITY = 'security'
+const SECURITY_TIMEOUT_MS = 10_000
+const FIND = 'find-generic-password'
+const ITEM_ARGUMENTS: ReadonlyArray<string> = ['-s', SERVICE, '-a', ACCOUNT]
+// The modification date of the item, `"mdat"<timedate>=0x… "20261014071518Z\000"`, in UTC.
+const SAVED_DATE_PATTERN = /"mdat"<timedate>=\S+\s+"(\d{4})(\d{2})(\d{2})/u
+
+function security(arguments_: ReadonlyArray<string>, input = ''): string | undefined {
+	try {
+		const { stdout } = execaSync(SECURITY, [...arguments_], { input, timeout: SECURITY_TIMEOUT_MS })
+
+		return stdout
+	} catch {
+		return undefined
+	}
+}
+
+function non_empty(value: string | undefined): string | undefined {
+	const trimmed = value?.trim()
+
+	return trimmed === undefined || trimmed === '' ? undefined : trimmed
+}
+
+function from_keychain(): string | undefined {
+	return non_empty(security([FIND, ...ITEM_ARGUMENTS, '-w']))
+}
+
+// The keychain first, then the environment; `undefined` when neither holds a token.
+function read(): string | undefined {
+	return from_keychain() ?? non_empty(process.env[VARIABLE])
+}
+
+// `security -i` reads its command from stdin, so the token is in no argument list `ps` could show.
+// The item is read back, because the interactive mode exits 0 whether or not the command succeeded.
+function save(token: string): boolean {
+	security(['-i'], `add-generic-password -U ${ITEM_ARGUMENTS.join(' ')} -w "${token}"\n`)
+
+	return from_keychain() === token
+}
+
+// The day the item was last written, `YYYY-MM-DD`; `undefined` when there is none.
+function saved_date(): string | undefined {
+	const attributes = security([FIND, ...ITEM_ARGUMENTS])
+	const match = attributes === undefined ? undefined : SAVED_DATE_PATTERN.exec(attributes)
+
+	return match?.slice(1).join('-')
+}
+
+// Whether `security` answers at all, asked before a sign-in whose token would have nowhere to go.
+function has_keychain(): boolean {
+	return security(['list-keychains']) !== undefined
+}
+
+const SETUP_HINT = 'Run `pnpm josh auth:setup` to save one.'
+
+const claude_token = { read, save, saved_date, has_keychain, VARIABLE, SETUP_HINT }
+
+export { claude_token }

package/scripts/auto-ok/auto-ok-judge-cli.ts

@@ -0,0 +1,125 @@
+import { fileURLToPath } from 'node:url'
+import { RUN_LANE_LABEL, RUN_SOLO_LABEL } from '#scripts/issue/issue-labels'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { session_cite } from '#scripts/issue/session-cite'
+import { cli_flags } from '#scripts/lib/cli-flags'
+import { auto_ok_judge_read } from './auto-ok-judge-read'
+import { auto_ok_judge_write } from './auto-ok-judge-write'
+
+// `josh auto-ok:judge` — the open issues `backlogrun` judges for `auto-ok` when a lane is free and
+// nothing is opted in (joshuafolkken/kit#3854), and the record of each judgement.
+//
+// Bare, it lists the issues that still owe a judgement: one number per line on stdout, or `none`, with
+// each title on stderr. The agent reads each one's body and comments (`josh issue:read`) and answers
+// with `--apply <N> --lane|--solo` or `--decline <N> --reason <text>`; which of the two is a reading of
+// the issue, never this command's.
+
+const ARGV_OFFSET = 2
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const NONE_TOKEN = 'none'
+const USAGE =
+	'Usage: josh auto-ok:judge [--apply <N> (--lane | --solo) | --decline <N> --reason <text>]'
+
+const OPTIONS = {
+	apply: { type: 'string' },
+	decline: { type: 'string' },
+	lane: { type: 'boolean' },
+	solo: { type: 'boolean' },
+	reason: { type: 'string' },
+} as const
+
+type Values = NonNullable<ReturnType<typeof cli_flags.values_of<typeof OPTIONS>>>
+
+type JudgeRequest =
+	| { kind: 'list' }
+	| { kind: 'apply'; issue: string; run_label: string }
+	| { kind: 'decline'; issue: string; reason: string }
+
+function run_label_of(values: Values): string | undefined {
+	if (values.lane === values.solo) return undefined
+
+	return values.lane === true ? RUN_LANE_LABEL : RUN_SOLO_LABEL
+}
+
+function apply_request(issue: string, values: Values): JudgeRequest | undefined {
+	const run_label = run_label_of(values)
+
+	return run_label === undefined ? undefined : { kind: 'apply', issue, run_label }
+}
+
+function decline_request(issue: string, values: Values): JudgeRequest | undefined {
+	const reason = values.reason?.trim() ?? ''
+
+	return reason === '' ? undefined : { kind: 'decline', issue, reason }
+}
+
+function request_of(values: Values): JudgeRequest | undefined {
+	const issue = values.apply ?? values.decline
+
+	if (issue === undefined) return { kind: 'list' }
+	if (!issue_number_shape.is_issue_number(issue)) return undefined
+
+	return values.apply === undefined ? decline_request(issue, values) : apply_request(issue, values)
+}
+
+function parse_request(argv: ReadonlyArray<string>): JudgeRequest | undefined {
+	const values = cli_flags.values_of(argv, OPTIONS)
+
+	if (values === undefined || (values.apply !== undefined && values.decline !== undefined)) {
+		return undefined
+	}
+
+	return request_of(values)
+}
+
+async function list(): Promise<number> {
+	const owed = await auto_ok_judge_read.owed()
+
+	if (owed === undefined) {
+		console.error('the open issues could not be read')
+
+		return FAILURE_EXIT_CODE
+	}
+
+	if (owed.length === 0) console.info(NONE_TOKEN)
+
+	for (const row of owed) {
+		console.error(session_cite.issue(row.number, row.title))
+		console.info(String(row.number))
+	}
+
+	return SUCCESS_EXIT_CODE
+}
+
+async function dispatch(request: JudgeRequest): Promise<number> {
+	const { apply, decline } = auto_ok_judge_write
+
+	if (request.kind === 'list') return await list()
+	if (request.kind === 'decline') return await decline(request.issue, request.reason)
+
+	return await apply(request.issue, request.run_label)
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const request = parse_request(argv)
+
+	if (request === undefined) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	return await dispatch(request)
+}
+
+// `process.exitCode` rather than `process.exit()`, so the report on standard output drains first.
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const auto_ok_judge_cli = { NONE_TOKEN, run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { auto_ok_judge_cli }

package/scripts/auto-ok/auto-ok-judge-read.ts

@@ -0,0 +1,95 @@
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { issue_label_schema } from '#scripts/git/git-schemas'
+import { read_json_listing } from '#scripts/git/parse-json-array'
+import { issue_watch_diff } from '#scripts/issue/issue-watch-diff'
+import { bounded_pool } from '#scripts/lib/bounded-pool'
+import { z } from 'zod'
+import { auto_ok_judge, type JudgeIssue } from './auto-ok-judge'
+
+// The reading half of `josh auto-ok:judge`: the open issues that still owe a judgement, shared by the
+// command's listing and the backlog driver's check for a free lane with nothing opted in.
+//
+// **The driver asks once a minute while it watches**, so it hands in a cache it keeps for its process:
+// an issue seen judged is remembered with its `updatedAt`, and its comments are read again only once
+// that moves — a body edit, a comment or a label change. Without it every watch minute would read the
+// comments of every candidate in the repository.
+
+// The listing cap `auto-ok:next` reads the opted-in pool under; the open backlog is read under the same.
+const LISTING_LIMIT = 200
+// How many comment listings run at once — a handful of `gh` processes, never one per candidate.
+const COMMENT_READ_WIDTH = 4
+
+const row_schema = z.looseObject({
+	number: z.number(),
+	title: z.string(),
+	body: z.string().nullish(),
+	labels: z.array(issue_label_schema),
+	updatedAt: z.string(),
+})
+
+interface JudgeRow extends JudgeIssue {
+	title: string
+	updated_at: string
+}
+
+// An issue's number to the `updatedAt` it was last seen judged at.
+type JudgedCache = Map<number, string>
+
+function to_row(raw: z.infer<typeof row_schema>): JudgeRow {
+	return {
+		number: raw.number,
+		title: raw.title,
+		body: raw.body ?? '',
+		labels: raw.labels.map((label) => label.name),
+		updated_at: raw.updatedAt,
+	}
+}
+
+// `undefined` when the listing could not be read, which is never "nothing to judge".
+async function read_candidates(): Promise<ReadonlyArray<JudgeRow> | undefined> {
+	const { json } = await git_gh_command.issue_list_open_for_judgement(LISTING_LIMIT)
+
+	if (json === undefined) return undefined
+
+	const listing = read_json_listing(json, row_schema)
+
+	if (listing.kind !== 'read') return undefined
+
+	return listing.rows.map((raw) => to_row(raw)).filter((row) => auto_ok_judge.is_candidate(row))
+}
+
+// `true` only for an issue known to owe a judgement: a failed comment read learns nothing, so it is
+// neither counted nor remembered.
+async function owes_judgement(row: JudgeRow, cache: JudgedCache): Promise<boolean> {
+	if (cache.get(row.number) === row.updated_at) return false
+
+	const comments = issue_watch_diff.parse_comments(
+		await git_gh_command.issue_list_comments(String(row.number)),
+	)
+
+	if (comments === undefined) return false
+	if (!auto_ok_judge.is_judged(row.body, comments)) return true
+
+	cache.set(row.number, row.updated_at)
+
+	return false
+}
+
+async function owed(cache: JudgedCache = new Map()): Promise<ReadonlyArray<JudgeRow> | undefined> {
+	const candidates = await read_candidates()
+
+	if (candidates === undefined) return undefined
+
+	const owing = await bounded_pool.bounded_map(
+		candidates,
+		COMMENT_READ_WIDTH,
+		async (row) => await owes_judgement(row, cache),
+	)
+
+	return candidates.filter((_row, index) => owing[index] === true)
+}
+
+const auto_ok_judge_read = { owed }
+
+export type { JudgedCache, JudgeRow }
+export { auto_ok_judge_read }

package/scripts/auto-ok/auto-ok-judge-write.ts

@@ -0,0 +1,109 @@
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { issue_label_schema } from '#scripts/git/git-schemas'
+import { parse_json_object_or_undefined } from '#scripts/git/parse-json-array'
+import { issue_auto_ok, type AutoOkDecision } from '#scripts/issue/issue-auto-ok'
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { AUTO_OK_LABEL } from '#scripts/issue/issue-labels'
+import { session_cite } from '#scripts/issue/session-cite'
+import { run_event_stream } from '#scripts/run/event/run-event-stream'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
+import { z } from 'zod'
+import { auto_ok_judge } from './auto-ok-judge'
+
+// The writing half of `josh auto-ok:judge`: the agent's judgement of one open issue, recorded on it.
+//
+// **An applied judgement still passes the mechanical exclusions** — `issue_auto_ok.exclusion_of` is
+// re-read against the labels as they stand, so a label added since the listing refuses the write
+// rather than racing it. **The run label lands before `auto-ok`**, so the pool never holds an opted-in
+// issue that `backlog:next` would withhold as untriaged. Both answers leave the judgement comment the
+// next listing reads as the record, and an applied one is a `note` on the board's 📌.
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const UNREADABLE = 'the issue could not be read'
+
+const issue_schema = z.object({ labels: z.array(issue_label_schema), body: z.string().nullish() })
+
+interface IssueRead {
+	labels: ReadonlyArray<string>
+	body: string
+}
+
+async function read_issue(issue: string): Promise<IssueRead | undefined> {
+	const raw = await git_gh_command.issue_get_labels_and_body(issue)
+	const parsed = raw === undefined ? undefined : parse_json_object_or_undefined(raw, issue_schema)
+
+	if (parsed === undefined) return undefined
+
+	return { labels: parsed.labels.map((label) => label.name), body: parsed.body ?? '' }
+}
+
+async function apply_labels(issue: string, run_label: string): Promise<string | undefined> {
+	for (const label of [run_label, AUTO_OK_LABEL]) {
+		// eslint-disable-next-line no-await-in-loop -- the run label must land before `auto-ok`
+		const write = await git_gh_command.issue_apply_label(issue, label)
+
+		if (!write.is_applied) return `could not apply \`${label}\`: ${write.reason}`
+	}
+
+	return undefined
+}
+
+async function record(issue: string, decision: AutoOkDecision, body: string): Promise<number> {
+	try {
+		await git_gh_command.issue_comment(issue, auto_ok_judge.comment_of(decision, body))
+	} catch {
+		console.error(`could not comment the judgement on ${session_cite.issue(issue)}`)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	console.info(issue_auto_ok.line_of(decision))
+
+	return SUCCESS_EXIT_CODE
+}
+
+function refused(issue: string, problem: string): number {
+	console.error(`${session_cite.issue(issue)}: ${problem}`)
+
+	return FAILURE_EXIT_CODE
+}
+
+async function apply_to(issue: string, run_label: string, read: IssueRead): Promise<number> {
+	const exclusion = issue_auto_ok.exclusion_of(read.labels)
+
+	if (exclusion !== undefined) return refused(issue, issue_auto_ok.line_of(exclusion))
+
+	const problem = await apply_labels(issue, run_label)
+
+	if (problem !== undefined) return refused(issue, problem)
+
+	const reason = `judged by backlogrun: no exclusion holds and no person's judgement is needed (${run_label})`
+
+	await run_event_stream_emit.emit(
+		run_event_stream.EVENT_KIND.NOTE,
+		`${issue_cite.plain(issue)} auto-ok applied (${run_label})`,
+	)
+
+	return await record(issue, { is_applied: true, reason }, read.body)
+}
+
+async function apply(issue: string, run_label: string): Promise<number> {
+	const read = await read_issue(issue)
+
+	if (read === undefined) return refused(issue, UNREADABLE)
+
+	return await apply_to(issue, run_label, read)
+}
+
+async function decline(issue: string, reason: string): Promise<number> {
+	const read = await read_issue(issue)
+
+	if (read === undefined) return refused(issue, UNREADABLE)
+
+	return await record(issue, { is_applied: false, reason }, read.body)
+}
+
+const auto_ok_judge_write = { apply, decline }
+
+export { auto_ok_judge_write }

package/scripts/auto-ok/auto-ok-judge.ts

@@ -0,0 +1,67 @@
+import { createHash } from 'node:crypto'
+import { issue_auto_ok, type AutoOkDecision } from '#scripts/issue/issue-auto-ok'
+import { AUTO_OK_LABEL, has_label_name } from '#scripts/issue/issue-labels'
+import type { WatchComment } from '#scripts/issue/issue-watch-diff'
+
+// The pure half of `josh auto-ok:judge`: which open issues `backlogrun` judges for `auto-ok` when a lane
+// is free and nothing is opted in, and whether one was already judged (joshuafolkken/kit#3854).
+//
+// **The mechanical exclusions are `issue_auto_ok.exclusion_of`**, the list a filing is judged by
+// (joshuafolkken/kit#3853), never a second one. What a label cannot answer — whether a policy decision,
+// an external account or a human visual check is needed — is the agent's reading of the body and the
+// comments, so this module only says which issues still owe that reading.
+//
+// **The record is the judgement comment itself.** It carries a digest of the body it judged, so an
+// issue is judged again only when its body changed or a person commented after it — the same line
+// `issue_watch_diff` draws between a person's update and an automated one.
+
+interface JudgeIssue {
+	number: number
+	labels: ReadonlyArray<string>
+	body: string
+}
+
+const MARKER_PREFIX = '<!-- josh:auto-ok-judged body='
+const MARKER_SUFFIX = ' -->'
+const MARKER_PATTERN = /<!-- josh:auto-ok-judged body=(?<digest>[\da-f]+) -->/u
+const DIGEST_LENGTH = 16
+const CRLF = '\r\n'
+const LF = '\n'
+
+function is_candidate(issue: JudgeIssue): boolean {
+	if (has_label_name(issue.labels, AUTO_OK_LABEL)) return false
+
+	return issue_auto_ok.exclusion_of(issue.labels) === undefined
+}
+
+// GitHub stores a body saved in its web editor with CRLF, so the digest is taken over LF alone.
+function body_digest(body: string): string {
+	const normalized = body.split(CRLF).join(LF)
+
+	return createHash('sha256').update(normalized).digest('hex').slice(0, DIGEST_LENGTH)
+}
+
+function digest_of(comment: WatchComment): string | undefined {
+	return MARKER_PATTERN.exec(comment.body)?.groups?.['digest']
+}
+
+// Judged when the newest judgement comment covers the body as it stands and no person has commented
+// since. A failed comment read never reaches here — the caller treats it as nothing learned.
+function is_judged(body: string, comments: ReadonlyArray<WatchComment>): boolean {
+	const judgement = comments.findLast((comment) => digest_of(comment) !== undefined)
+
+	if (judgement === undefined || digest_of(judgement) !== body_digest(body)) return false
+
+	return comments.every((comment) => comment.id <= judgement.id || comment.is_automated)
+}
+
+function comment_of(decision: AutoOkDecision, body: string): string {
+	const marker = `${MARKER_PREFIX}${body_digest(body)}${MARKER_SUFFIX}`
+
+	return `${issue_auto_ok.line_of(decision)}${LF}${LF}${marker}`
+}
+
+const auto_ok_judge = { comment_of, is_candidate, is_judged }
+
+export type { JudgeIssue }
+export { auto_ok_judge }