@joshuafolkken/kit 1.1383.0 → 1.1435.0

package/prompts/review.md

@@ -27,6 +27,28 @@ is a verification pass over the fixes, not the first review again
 
 ---
 
+## Before round 1 — the implementer's self-check
+
+**Answer these five over your own diff before the scoped pair that precedes round 1.** A round-1
+High/Medium makes round 2 due, and most of them are of a kind the implementer clears more cheaply
+than a reviewer finds: in a sample of 135 round-1 High/Medium findings, about two in three fell under one of these questions. Fix what an answer turns up; the review, its
+severity tests and the round cap are unchanged.
+
+1. **Tests pin the change** — for each condition, branch or call you added or changed, name the test
+   that turns red when it is deleted or inverted, and check its fixture actually reaches that branch
+   (no assert on a string the code never draws, no comparison against a literal copy).
+2. **Prose matches the code** — grep the docs, prompts and comments for the old wording of every
+   behavior, constant, command and heading you changed, moved or removed, `"the table above"` and
+   rewritten sentences included.
+3. **Failure is not a negative answer** — every timeout, non-zero exit or `gh` failure on a path you
+   touched returns something a caller can tell apart from `false`, `undefined` or "nothing found".
+4. **Every caller moved with it** — grep every reference to a function, list or command you changed,
+   and update each sibling path (the other CLI, the registry, the consumer side) in the same change.
+5. **The Issue is met on HEAD** — the premises you relied on hold on the current tree, and each
+   acceptance criterion is checked off one by one against the diff.
+
+---
+
 ## Review level (decided by `pnpm josh review:brief --level-only`, never by judgement)
 
 **Run `pnpm josh review:brief --level-only` and use what it prints** — `low` or `medium`, from the

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/backlog/backlog-drive-cli.ts

@@ -79,10 +79,7 @@ async function read_offer(
 	state: DriveState,
 	context: DriveContext,
 ): Promise<OfferRead | undefined> {
-	await backlog_drive_owner.assert_current(context.owner)
-	const carry = await read_record()
-
-	if (carry === undefined) return undefined
+	const carry = await backlog_drive_owner.assert_current(context.owner)
 	const named = await backlog_drive_named_offer.read(carry, state, context)
 	if (named !== undefined) return named
 
@@ -269,6 +266,7 @@ const backlog_drive_cli = {
 	merge_token,
 	offer_argv: backlog_drive_offer_argv.offer_argv,
 	parse: backlog_drive_args.parse,
+	read_offer,
 	resume_line: backlog_drive_args.resume_line,
 	run,
 	to_offer,

package/scripts/backlog/backlog-drive-epic.ts

@@ -1,3 +1,4 @@
+import { epic_triage } from '#scripts/epic/epic-triage'
 import { git_gh_repo } from '#scripts/gh/git-gh-repo'
 import { issue_cite } from '#scripts/issue/issue-cite'
 import { issue_number_shape } from '#scripts/issue/issue-number-shape'
@@ -12,7 +13,12 @@ import { backlog_offer } from './backlog-offer'
 // is runnable, without `run:add` and without waking a parent session.
 //
 // **Only what needs a person is handed back.** `stop` means every child left waits on a person, which a
-// judgment session reads. A failed `epic:next` is either a network blip or a broken graph (a cycle, an
+// judgment session reads. `triage` means a child carries neither `run:solo` nor `run:lane`, so
+// `epic:next --lanes` offers nothing until a session judges it — it exits 0 and repeats on every pass,
+// so waiting on it would never end. It is handed back under its own word, as the pool path's is, never
+// as `epic #N`: that verdict sends the session to run the epic's children, and the single-child
+// `epic:next` it asks there is not triage-gated, so it would launch the untriaged child instead of
+// labelling it. A failed `epic:next` is either a network blip or a broken graph (a cycle, an
 // undeclared order, an unreadable child), and its exit code does not tell them apart — so a failure is
 // a `wait` that retries on the next pass, and `backlog:offer`'s consecutive-retry limit of them hands the
 // epic back too, rather than waiting out the idle budget on an anomaly nobody is shown.
@@ -21,6 +27,7 @@ const NO_RETRIES = 0
 const SUCCESS_EXIT_CODE = 0
 const FIRST_LINE = 0
 const WAIT: OfferRead = { verdict: 'wait', issues: [], retries: NO_RETRIES }
+const TRIAGE: OfferRead = { ...WAIT, verdict: epic_triage.TRIAGE_VERDICT }
 
 // `--lanes` lists every child a free lane could take, so one the loop already knows about is passed
 // over rather than standing in front of the rest. `undefined` is an answer that could not be read.
@@ -53,22 +60,31 @@ function child_offer(children: ReadonlyArray<string>, state: DriveState): OfferR
 	return child === undefined ? WAIT : { verdict: 'run', issues: [child], retries: NO_RETRIES }
 }
 
+// The answers only a judgment session can move.
+function judgment_offer(epic: string, token: string): OfferRead | undefined {
+	if (token === 'stop') return handed_back(epic)
+
+	return token === epic_triage.TRIAGE_VERDICT ? TRIAGE : undefined
+}
+
 async function answered_offer(
 	epic: string,
 	answers: ReadonlyArray<string>,
 	state: DriveState,
 	owner: string,
 ): Promise<OfferRead> {
-	const token = answers[FIRST_LINE]
+	const token = answers[FIRST_LINE] ?? ''
 
-	if (token !== undefined && issue_number_shape.ISSUE_NUMBER_PATTERN.test(token)) {
-		return child_offer(answers, state)
-	}
-
-	if (token === 'stop') return handed_back(epic)
+	if (issue_number_shape.ISSUE_NUMBER_PATTERN.test(token)) return child_offer(answers, state)
+	const judgment = judgment_offer(epic, token)
+	if (judgment !== undefined) return judgment
 
 	if (token === 'complete') {
-		await backlog_drive_named.mark_done(epic, { outcome: 'merged', code: 0, token: 'none' }, owner)
+		await backlog_drive_named.mark_done(
+			epic,
+			{ outcome: 'merged', code: 0, token: 'none', is_offer: true },
+			owner,
+		)
 	}
 
 	return WAIT

package/scripts/backlog/backlog-drive-launch.ts

@@ -1,5 +1,6 @@
 import { git_stash } from '#scripts/git/stash/git-stash'
 import { lane_launch_cli, type LaunchOutcome } from '#scripts/lane/lane-launch-cli'
+import { run_event_setup } from '#scripts/run/event/run-event-setup'
 import { backlog_drive_owner } from './backlog-drive-owner'
 
 // The driver's lane launch. The parent that ran `josh latest` in the primary
@@ -28,9 +29,13 @@ async function latest_stash(): Promise<string | undefined> {
 
 async function launch(issue: string, owner: string): Promise<LaunchOutcome['kind']> {
 	await backlog_drive_owner.assert_current(owner)
+	await run_event_setup.emit(run_event_setup.opening_lane(issue))
 
 	const outcome = await lane_launch_cli.launch_lane({ issue, stash: await latest_stash() })
 
+	// A refusal the driver waits out writes nothing else, so the lane's stage is ended here.
+	if (outcome.kind !== 'launched') await run_event_setup.emit(run_event_setup.STAGE.NO_CHILD)
+
 	return outcome.kind
 }
 

package/scripts/backlog/backlog-drive-named-offer.ts

@@ -10,6 +10,7 @@ import { backlog_budget } from './backlog-budget'
 import type { DriveState, OfferRead } from './backlog-drive'
 import { backlog_drive_epic } from './backlog-drive-epic'
 import { backlog_drive_named } from './backlog-drive-named'
+import { backlog_drive_unread } from './backlog-drive-unread'
 
 interface NamedContext {
 	is_only: boolean
@@ -67,12 +68,16 @@ async function classify(
 ): Promise<OfferRead> {
 	const result = await issue_state_cli.read_issue(issue)
 
-	if (result.kind !== 'state') return { verdict: 'issue-state', issues: [], retries: NO_RETRIES }
+	if (result.kind !== 'state') return backlog_drive_unread.offer(issue, result, state.retries)
 
 	const outcome = settled_outcome(result.state)
 
 	if (outcome !== undefined) {
-		await backlog_drive_named.mark_done(issue, { outcome, code: 0, token: 'none' }, owner)
+		await backlog_drive_named.mark_done(
+			issue,
+			{ outcome, code: 0, token: 'none', is_offer: true },
+			owner,
+		)
 
 		return { verdict: 'wait', issues: [], retries: NO_RETRIES }
 	}

package/scripts/backlog/backlog-drive-named.ts

@@ -55,7 +55,9 @@ function is_done(result: MergeResult): boolean {
 		return result.code === 0 && result.token !== MERGE_TOKEN.BUSY
 	}
 
-	return result.outcome === 'failed' && result.code === 0 && result.token !== MERGE_TOKEN.STOP
+	return (
+		result.outcome === 'failed' && result.code === 0 && !run_merge_token.is_control_stop(result)
+	)
 }
 
 function can_mark(carry: RunCarry, issue: string, owner: string): boolean {
@@ -125,7 +127,7 @@ async function reconcile(
 		const outcome = parked.has(issue) ? 'parked' : 'merged'
 
 		// eslint-disable-next-line no-await-in-loop -- each mark rewrites the same carry file
-		await mark_done(String(issue), { outcome, code: 0, token: 'none' }, owner)
+		await mark_done(String(issue), { outcome, code: 0, token: 'none', is_offer: true }, owner)
 	}
 }
 

package/scripts/backlog/backlog-drive-owner.ts

@@ -1,4 +1,18 @@
-import { run_carry, type RunCarry } from '#scripts/run/carry/run-carry'
+import { existsSync } from 'node:fs'
+import { poll } from '#scripts/lib/poll'
+import { run_carry, type CarryRead, type RunCarry } from '#scripts/run/carry/run-carry'
+import { run_carry_ended } from '#scripts/run/carry/run-carry-ended'
+import { backlog_budget } from './backlog-budget'
+
+// **A record that does not read is asked again before the driver gives up on it.** The driver is the
+// only thing looking for work during the idle watch, so ending on one failed read throws away whatever
+// is left of the watch. The read is repeated at the offer's own interval, and
+// the count bounds it: a record that stays unreadable still ends the driver, with the reason said.
+const READ_ATTEMPTS = 6
+const ENDED_MESSAGE = 'The carry record is no longer active.'
+
+// The run this driver last read, so a record that is gone can be told from one `run:carry --end` ended.
+const seen: { started_at?: string } = {}
 
 function owns_record(carry: RunCarry, owner: string): boolean {
 	const current = run_carry.owner_of(Number(owner))
@@ -7,16 +21,69 @@ function owns_record(carry: RunCarry, owner: string): boolean {
 	return has_owner && run_carry.is_owner_live(carry) && !carry.is_handed_off
 }
 
-async function assert_current(owner: string): Promise<void> {
+// `--end` records the run it removes, so an ended run answers at once rather than after the re-reads.
+function is_ended(directory: string): boolean {
+	return run_carry_ended.has_ended(run_carry_ended.ended_path(directory), seen.started_at)
+}
+
+// Whether the file is there is said beside the read, because `none` is the answer both to a record
+// that is gone and to one that is present and could not be opened.
+function unread_note(read: CarryRead, directory: string): string {
+	const presence = existsSync(run_carry.carry_path(directory)) ? 'present' : 'absent'
+
+	return `The carry record read \`${read.kind}\` with its file ${presence}`
+}
+
+function is_settled(read: CarryRead, directory: string): boolean {
+	if (read.kind === 'carried' || is_ended(directory)) return true
+
+	console.error(`${unread_note(read, directory)}; reading it again.`)
+
+	return false
+}
+
+async function read_record(directory: string): Promise<CarryRead> {
+	const target = run_carry.carry_path(directory)
+	let read: CarryRead = { kind: 'none' }
+
+	await poll.poll_until(
+		async () => {
+			read = run_carry.read_carry(target)
+
+			return is_settled(read, directory)
+		},
+		{
+			attempts: READ_ATTEMPTS,
+			interval_ms: backlog_budget.OFFER_INTERVAL_MS,
+			sleeper: async (duration_ms) => {
+				await poll.sleep(duration_ms)
+			},
+		},
+	)
+
+	return read
+}
+
+function unread_message(read: CarryRead, directory: string): string {
+	if (is_ended(directory)) return ENDED_MESSAGE
+
+	return `${unread_note(read, directory)}, ${String(READ_ATTEMPTS)} times in a row.`
+}
+
+async function assert_current(owner: string): Promise<RunCarry> {
 	const directory = await run_carry.repository_directory()
 	if (directory === undefined) throw new Error('The carry record cannot be located.')
 
-	const read = run_carry.read_carry(run_carry.carry_path(directory))
-	if (read.kind !== 'carried') throw new Error('The carry record is no longer active.')
+	const read = await read_record(directory)
+	if (read.kind !== 'carried') throw new Error(unread_message(read, directory))
 
 	if (!owns_record(read.carry, owner)) {
 		throw new Error('The driver no longer owns the carry record.')
 	}
+
+	seen.started_at = read.carry.started_at
+
+	return read.carry
 }
 
-export const backlog_drive_owner = { assert_current }
+export const backlog_drive_owner = { READ_ATTEMPTS, assert_current }

package/scripts/backlog/backlog-drive-unread.ts

@@ -0,0 +1,56 @@
+import { issue_cite } from '#scripts/issue/issue-cite'
+import type { StateRead } from '#scripts/issue/issue-state-cli'
+import type { OfferRead } from './backlog-drive'
+import { backlog_offer } from './backlog-offer'
+
+// **A named issue whose state did not read is asked again before a session hears of it.** The read is
+// one `gh` request, and a dropped connection fails it for a moment and no longer: handing that to a
+// session costs a wake that can only cut and hand the loop back. So the failure is a `wait` that reads
+// again on the next pass — the driver keeps collecting children meanwhile — and `backlog:offer`'s
+// consecutive-retry limit bounds it, the count `backlog-drive-epic.ts` advances for a failed `epic:next`.
+//
+// **What is handed back is `offer`, with the issue and the reason on stderr.** That is the row a session
+// already reads for an offer that produced nothing to start: report what stderr printed, pick no issue
+// by hand. A number that resolves to nothing is an answer rather than a gap, so it is not asked again.
+
+type UnreadState = Exclude<StateRead, { kind: 'state' }>
+
+const NO_RETRIES = 0
+// The loop's own word for an offer it could not use (`backlog-drive.ts` → `ask_offer`).
+const HANDED_BACK = 'offer'
+const UNKNOWN_REASON = 'unknown reason'
+
+function cause_of(read: UnreadState): string {
+	if (read.kind === 'missing') return 'the number does not resolve'
+	const status = read.status === undefined ? [] : [`status ${String(read.status)}`]
+
+	return [read.reason ?? UNKNOWN_REASON, ...status].join(', ')
+}
+
+function note_of(issue: string, read: UnreadState): string {
+	return `The state of named issue ${issue_cite.plain(issue)} could not be read (${cause_of(read)})`
+}
+
+function handed_back(note: string): OfferRead {
+	console.error(note)
+
+	return { verdict: HANDED_BACK, issues: [], retries: NO_RETRIES }
+}
+
+// `retries` is the count of consecutive failed offers before this one. A named epic's failed
+// `epic:next` advances it too, so the note counts offers, never state reads.
+function offer(issue: string, read: UnreadState, retries: number): OfferRead {
+	const note = note_of(issue, read)
+	if (read.kind === 'missing') return handed_back(`${note}; check the number and the repository.`)
+	const failures = retries + 1
+
+	if (failures >= backlog_offer.RETRY_LIMIT) {
+		return handed_back(`${note}; the offer failed ${String(failures)} times in a row.`)
+	}
+
+	console.error(`${note}; reading it again.`)
+
+	return { verdict: 'wait', issues: [], retries: failures }
+}
+
+export const backlog_drive_unread = { HANDED_BACK, offer }

package/scripts/backlog/backlog-drive.ts

@@ -26,10 +26,14 @@ const RUN_VERDICT = 'run'
 const STOP_VERDICT = 'stop'
 // How the loop reads each `run:merge` token — keyed by the producer's own type, so a token added there
 // is a type error here until it is classified. `hand-back` ends the loop at once: a hand-off, a person's
-// stop, the environment down, a foreign owner, an unreadable state. `stop` — a parked backlog or the
-// failure guard — is the offer's `stop` reached through a merge: the child is collected, nothing more
-// starts, and the children still in flight are collected before the loop ends. `await` is a cut resumed
-// in place: the same lane is awaited again.
+// stop, the environment down, a foreign owner, an unreadable state. `stop` — the failure guard, or a
+// failed child left unparked — collects the child, starts nothing more, and collects the children still
+// in flight before the loop ends. `await` is a cut resumed in place: the same lane is awaited again.
+//
+// **The offer `run:merge` passes through is never read here** (joshuafolkken/kit#3781): its `stop` —
+// only person-waiting issues left — is spelled like the control one, and acting on it ended the run
+// without the idle watch. The loop asks `backlog:offer` on the next pass instead, so whether a parked
+// backlog waits or ends is `backlog:budget`'s alone, after a merge as after any other pass.
 type TokenHandling = 'hand-back' | 'stop' | 'await'
 const TOKEN_HANDLING: Readonly<Record<MergeToken, TokenHandling>> = {
 	[MERGE_TOKEN.OVER]: 'hand-back',
@@ -103,7 +107,7 @@ interface DriveEnd {
 	is_finish?: boolean | undefined
 }
 
-type Collected = Pick<MergeResult, 'token' | 'outcome'>
+type Collected = Pick<MergeResult, 'token' | 'outcome' | 'is_offer'>
 
 interface DrivePorts {
 	// Whether a child's process has confirmed-ended — `lane:await`'s re-confirmed check in production.
@@ -209,15 +213,19 @@ function collected_state(
 // One finished child: handed back on an immediate token, otherwise collected.
 async function collect(issue: string, state: DriveState, ports: DrivePorts): Promise<PassResult> {
 	const collected = await ports.merge(issue)
-	const { token } = collected
+	const { token, is_offer } = collected
 
 	// An empty first line is a `run:merge` that failed before printing one: never read as a collection.
+	// An offer's `retry` is `backlog:next`'s transport answer, left to the next `backlog:offer`.
 	if (token === '') return ended('merge', state, undefined, issue)
-	if (IMMEDIATE_TOKENS.has(token)) return ended('merge', state, token, issue)
+	if (!is_offer && IMMEDIATE_TOKENS.has(token)) return ended('merge', state, token, issue)
 
 	const next = collected_state(issue, collected, state, ports.now().toISOString())
 
-	return { kind: 'continue', state: token === MERGE_TOKEN.STOP ? merge_stopped(issue, next) : next }
+	return {
+		kind: 'continue',
+		state: run_merge_token.is_control_stop(collected) ? merge_stopped(issue, next) : next,
+	}
 }
 
 async function collect_finished(state: DriveState, ports: DrivePorts): Promise<PassResult> {