@joshuafolkken/kit 1.1128.0 → 1.1166.0

package/scripts/issue/issue-report-failures.ts

@@ -1,3 +1,5 @@
+import { capped_output } from '#scripts/document/capped-print'
+
 // The failure report `issue:read` and `issue:state` share (joshuafolkken/kit#3046). Both read a batch
 // of numbers, print a block for each one that answered, and name every one that did not; only the
 // result kind that counts as an answer and what a gap must not be mistaken for differ between them.
@@ -22,10 +24,12 @@ interface FailureTerms<K extends string> {
 	misreading: string
 }
 
-function print_blocks(blocks: ReadonlyArray<string>, separator: string): void {
+// Under the Bash output cap, or as part files past it — a batch of long threads is the shape that
+// overflowed (joshuafolkken/kit#3143).
+function print_blocks(blocks: ReadonlyArray<string>, separator: string, label: string): void {
 	if (blocks.length === 0) return
 
-	console.info(blocks.join(separator))
+	capped_output.capped_print(blocks.join(separator), label)
 }
 
 // A number that resolves to nothing is an answer — a typo, or another repository's number quoted in

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

@@ -107,7 +107,7 @@ function format_duplicate(candidate: DuplicateCandidate): string {
 	const epic = candidate.epic === undefined ? '' : ` (epic #${String(candidate.epic)})`
 	// The reader does two different things with the two states, so the row has to say which it is: an
 	// open candidate means somebody is already tracking this, a closed one means it may already be
-	// done — and the second is the exit `SKILL.md` → §2g names, not a second filing.
+	// done — and the second is the exit `issue-comments.md` names, not a second filing.
 	const closed = candidate.is_closed === true ? ' (closed)' : ''
 
 	return `  #${String(candidate.number)}  ${score}  ${candidate.title}${closed}${epic}`
@@ -211,7 +211,7 @@ function named_epics(draft: BacklogIssue, issues: ReadonlyArray<BacklogIssue>):
 		.map((issue) => issue.number)
 }
 
-// A person naming the epic is the strongest signal there is — it is what §2a's `into <target>` suffix
+// A person naming the epic is the strongest signal there is — it is what `into-target.md`'s `into <target>` suffix
 // means — so it is reported ahead of whatever the candidate search concluded, with the candidates
 // still named beside it.
 function format_named_epics(epics: ReadonlyArray<number>, decision: BundleDecision): Array<string> {

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

@@ -170,7 +170,7 @@ async function read_all(request: StateRequest): Promise<ReadonlyArray<IssueRepor
 }
 
 // `[]` for a number that produced no state, so one unresolvable number costs the others nothing.
-// The heading is withheld for a single number: `.claude/skills/workflow-commands/SKILL.md` §2z and
+// The heading is withheld for a single number: `.claude/skills/workflow-commands/needs-human-review.md` and
 // `.claude/skills/diag/SKILL.md` read that report's three lines verbatim.
 function state_blocks(report: IssueReport, should_attribute: boolean): ReadonlyArray<string> {
 	if (report.result.kind !== 'state') return []
@@ -188,7 +188,7 @@ function print_states(reports: ReadonlyArray<IssueReport>): void {
 	const should_attribute = reports.length > 1
 	const blocks = reports.flatMap((report) => state_blocks(report, should_attribute))
 
-	issue_report_failures.print_blocks(blocks, BLOCK_SEPARATOR)
+	issue_report_failures.print_blocks(blocks, BLOCK_SEPARATOR, 'issue:state')
 }
 
 async function run(argv: ReadonlyArray<string>): Promise<number> {

package/scripts/issue/issue-state.ts

@@ -88,8 +88,8 @@ function format_issue_state(state: IssueState): string {
 
 // The same three lines, under the number they belong to. Kept as a separate function rather than a
 // flag on the one above, so the single-number report has no branch that could ever prepend a fourth
-// line to it: `.claude/skills/workflow-commands/SKILL.md` §2z and `.claude/skills/diag/SKILL.md`
-// read those three verbatim, and §2z's `needs-human-review` stop is decided from them.
+// line to it: `.claude/skills/workflow-commands/needs-human-review.md` and `.claude/skills/diag/SKILL.md`
+// read those three verbatim, and `needs-human-review.md`'s `needs-human-review` stop is decided from them.
 function format_attributed_issue_state(issue_number: string, state: IssueState): string {
 	return `${ISSUE_LABEL}${issue_number}\n${format_issue_state(state)}`
 }

package/scripts/issue/issue-wip.ts

@@ -0,0 +1,70 @@
+import { delivered_rules } from '#scripts/rules/delivered-rules'
+import { INTERRUPT_ROUTE_LABEL, SPLIT_ROUTE_LABEL, TIER_A_ROUTE_LABEL } from './issue-labels'
+
+// The WIP cap at the call that files (joshuafolkken/kit#3181). The count used to be a hand-run
+// `gh api … | wc -l` the agent compared with the cap itself; `josh issue:file` now reads it and asks
+// the exemption question before anything is sent, the same hold `--distinct` places on a duplicate.
+// What stays judgement — whether a filing is exempt — is declared by the route or by `--over-cap`.
+
+const WITHIN = 'within'
+const EXEMPT = 'exempt'
+const HELD = 'held' as const
+
+type WipVerdict = typeof WITHIN | typeof EXEMPT | typeof HELD
+
+// Each route is an exempt category by definition: a prerequisite or upstream defect (`tier-a`) and a
+// split child block the run, and an interrupt is one of the three tests. `review-cap` is the review
+// round cap's branch 2, which `wip-cap.md` counts as discretionary, so it is held like no route at all.
+const EXEMPT_ROUTES: ReadonlySet<string> = new Set([
+	TIER_A_ROUTE_LABEL,
+	SPLIT_ROUTE_LABEL,
+	INTERRUPT_ROUTE_LABEL,
+])
+
+const HELD_MESSAGE =
+	'✖ over the WIP cap: close one first; nothing honestly closable means do not file — a discretionary ' +
+	'filing waits. An interrupt meeting one of three tests (a verification answers wrongly, a documented ' +
+	'workflow cannot complete, or data is lost or written outside the repository) files with ' +
+	'`--route interrupt`; a filing the run is blocked by reissues with `--over-cap`. Either way, state ' +
+	'the overage (`prompts/collaboration-workflow/wip-cap.md`).'
+
+const UNREAD_MESSAGE =
+	'⚠ wip: could not count the open Issues — the filing goes on unchecked against the cap ' +
+	'(`prompts/collaboration-workflow/wip-cap.md`).'
+
+interface WipFiling {
+	route: string | undefined
+	is_over_cap: boolean
+}
+
+function is_exempt(filing: WipFiling): boolean {
+	return filing.is_over_cap || (filing.route !== undefined && EXEMPT_ROUTES.has(filing.route))
+}
+
+// The cap is "more than `WIP_CAP` open", so exactly the cap is still within it.
+function verdict_of(count: number, filing: WipFiling): WipVerdict {
+	if (count <= delivered_rules.WIP_CAP) return WITHIN
+
+	return is_exempt(filing) ? EXEMPT : HELD
+}
+
+function count_line(count: number, repo: string, verdict: WipVerdict): string {
+	return `wip: ${String(count)} open in ${repo} · cap ${String(delivered_rules.WIP_CAP)} · ${verdict}`
+}
+
+// The listing's JSON is an array of rows; anything else is unreadable rather than zero, because zero
+// would pass every filing as within the cap.
+function count_of(json: string): number | undefined {
+	try {
+		const parsed: unknown = JSON.parse(json)
+
+		return Array.isArray(parsed) ? parsed.length : undefined
+	} catch {
+		return undefined
+	}
+}
+
+const issue_wip = { HELD, HELD_MESSAGE, UNREAD_MESSAGE, verdict_of, count_line, count_of }
+
+export type { WipVerdict }
+export { issue_wip }

package/scripts/josh/hook-decision.ts

@@ -38,6 +38,7 @@ type HookPayload = z.infer<typeof payload_schema>
 
 const HOOK_EVENT_NAME = 'PreToolUse'
 const DENY_DECISION = 'deny'
+const ALLOW_DECISION = 'allow'
 // No record means nothing has been refused yet, and every span began after instant zero — which is
 // the answer wanted: the first qualifying accumulation of a run is refused.
 const NEVER_MS = 0
@@ -84,6 +85,21 @@ function deny_envelope(reason: string): string {
 	})
 }
 
+// **A rewrite, not a refusal** (joshuafolkken/kit#3154): the call proceeds with `updated_input` merged
+// over its own. `allow` is the decision the harness applies an `updatedInput` under; a settings `deny`
+// rule still wins over it, so this never widens what the call may do.
+function rewrite_envelope(updated_input: Record<string, unknown>, context: string): string {
+	return JSON.stringify({
+		systemMessage: context,
+		hookSpecificOutput: {
+			hookEventName: HOOK_EVENT_NAME,
+			permissionDecision: ALLOW_DECISION,
+			updatedInput: updated_input,
+			additionalContext: context,
+		},
+	})
+}
+
 // **A notice, not a decision.** It carries no `permissionDecision`, so the call proceeds exactly as it
 // would have; `additionalContext` is what reaches the model, and `systemMessage` is what the person
 // watching sees. Both are filled because either channel alone leaves one of the two blind — and the
@@ -470,6 +486,7 @@ const hook_decision = {
 	notice_envelope,
 	parse_hook_payload,
 	report_no_payload,
+	rewrite_envelope,
 	stamp_fault,
 	write_decision,
 	write_outcome,

package/scripts/josh/josh-commands-development.ts

@@ -115,6 +115,16 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		// `UserPromptSubmit`, so it must stay eligible for in-process dispatch rather than pay a second
 		// tsx start each turn. It calls `process.loadEnvFile` itself through the shared loader.
 	},
+	'codex:hook-adapter': {
+		script: 'scripts/hooks/codex-hook-adapter.ts',
+		description:
+			'Codex hook: run the pretool or posttool guard on a Codex payload (reads the tool call on stdin)',
+		category: 'Development',
+		reference: ['<pretool|posttool>', 'automation', ['none']],
+		// The live-source fallback `scripts/hooks/run-hook.sh` derives from the `codex-hook-adapter`
+		// bundle name (joshuafolkken/kit#3184). **No `tsx_arguments`**, the same as `pretool:guard`
+		// above: it runs before every guarded Codex call.
+	},
 	'cspell:dot': {
 		script: 'scripts/lint/cspell-cached.ts',
 		description: 'Run spell check including dotfiles',

package/scripts/josh/josh-commands-issue.ts

@@ -66,10 +66,10 @@ const ISSUE_COMMANDS: Record<string, CommandEntry> = {
 	'issue:file': {
 		script: 'scripts/issue/issue-file-cli.ts',
 		description:
-			'File an Issue with every filing step: lint, Origin, duplicate scout, labels, then epic:bundle',
+			'File an Issue with every filing step: lint, Origin, WIP cap, duplicate scout, labels, then epic:bundle',
 		category: 'AI tools',
 		reference: [
-			'<title> --body-file <path> --depth <0|1|2> [--route <route>] [--label <name>] [--repo <owner/repo>] [--distinct <N,…>]',
+			'<title> --body-file <path> --depth <0|1|2> [--route <route>] [--label <name>] [--repo <owner/repo>] [--distinct <N,…>] [--over-cap] [--no-auto-ok]',
 			'automation',
 			['network'],
 		],

package/scripts/josh/josh-commands-lane.ts

@@ -59,7 +59,7 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 		description:
 			'Block until any of the named in-flight lane children completes; prints which one finished',
 		category: 'AI tools',
-		reference: ['<issue> [<issue>...]', 'automation', ['processes']],
+		reference: ['<issue> [<issue>...] [--owner <pid>]', 'automation', ['files', 'processes']],
 		default_script_arguments: ['await'],
 	},
 	'lane:launch': {

package/scripts/josh/josh-commands-project.ts

@@ -22,6 +22,13 @@ const PROJECT_COMMANDS: Record<string, CommandEntry> = {
 			['files', 'git', 'network', 'processes'],
 		],
 	},
+	'dogfood:commit': {
+		script: 'scripts/dogfood/dogfood-commit-cli.ts',
+		description: "Make the first commit of a dogfood run's own kit-test-* project",
+		category: 'Project',
+		reference: ['<dir>', 'automation', ['files', 'git']],
+		is_kit_only: true,
+	},
 	init: {
 		script: 'scripts/init/init.ts',
 		description: 'Initialize config in a new project',

package/scripts/lane/lane-await.ts

@@ -1,5 +1,6 @@
 import { spawnSync } from 'node:child_process'
 import { setTimeout as sleep } from 'node:timers/promises'
+import { parseArgs } from 'node:util'
 import { run_liveness } from '#scripts/run/run-liveness'
 import { lane_child_invocation } from './lane-child-invocation'
 import { lane_handoff } from './lane-handoff'
@@ -33,6 +34,16 @@ interface AwaitState {
 	is_settled?: boolean
 }
 
+interface AwaitArguments {
+	issues: ReadonlyArray<string>
+	owner: number | undefined
+}
+
+interface RawAwaitArguments {
+	positionals: Array<string>
+	values: { owner?: string | undefined }
+}
+
 // Injectable for testing -- the CLI never overrides these.
 interface AwaitOptions {
 	is_running?: (issue: string) => boolean
@@ -67,6 +78,39 @@ async function is_settled_default(issue: string): Promise<boolean> {
 	return (await run_liveness.read_child_settled(issue)) === true
 }
 
+// An unknown flag or a flag without its value is `undefined`, which is usage.
+function read_await_args(rest: ReadonlyArray<string>): RawAwaitArguments | undefined {
+	try {
+		return parseArgs({
+			args: [...rest],
+			allowPositionals: true,
+			strict: true,
+			options: { owner: { type: 'string' } },
+		})
+	} catch {
+		return undefined
+	}
+}
+
+// Every positional is an issue number, at least one is given, and `--owner` is a pid.
+function is_valid(raw: RawAwaitArguments): boolean {
+	const { owner } = raw.values
+	const numbers = owner === undefined ? raw.positionals : [...raw.positionals, owner]
+
+	return raw.positionals.length > 0 && numbers.every((value) => ISSUE_PATTERN.test(value))
+}
+
+// The issues to wait on and the waiting session's pid, or `undefined` for anything else.
+function parse_arguments(rest: ReadonlyArray<string>): AwaitArguments | undefined {
+	const raw = read_await_args(rest)
+
+	if (raw === undefined || !is_valid(raw)) return undefined
+
+	const { owner } = raw.values
+
+	return { issues: raw.positionals, owner: owner === undefined ? undefined : Number(owner) }
+}
+
 function make_initial_state(is_settled: boolean): AwaitState {
 	return { appeared: false, disappeared_at: undefined, first_polled_at: undefined, is_settled }
 }
@@ -187,13 +231,13 @@ async function wait_for_any(
 }
 
 const lane_await = {
-	ISSUE_PATTERN,
 	NEVER_APPEARED_TIMEOUT_MS,
 	RECONFIRM_MS,
 	check_issue,
 	is_process_running_default,
+	parse_arguments,
 	wait_for_any,
 }
 
-export type { AwaitState, CheckConfig }
+export type { AwaitArguments, AwaitState, CheckConfig }
 export { lane_await }

package/scripts/lane/lane-cli.ts

@@ -6,6 +6,7 @@ import type { OpenIssueData } from '#scripts/git/schemas'
 import { issue_cite, type IssueCiter } from '#scripts/issue/issue-cite'
 import { error_text } from '#scripts/lib/error-message'
 import { run_carry } from '#scripts/run/run-carry'
+import { run_carry_reclaim } from '#scripts/run/run-carry-reclaim'
 import { lane_await } from './lane-await'
 import { lane_close, type CloseOutcome, type SweepOutcome } from './lane-close'
 import { lane_dispatch, type DispatchOutcome } from './lane-dispatch'
@@ -40,7 +41,7 @@ const USAGE = [
 	'       josh lane:prune',
 	'       josh lane:output <issue-number> [<path>]',
 	'       josh lane:dispatch <issue-number>',
-	'       josh lane:await <issue-number> ...',
+	'       josh lane:await <issue-number> ... [--owner <pid>]',
 ].join('\n')
 
 type Handler = (rest: ReadonlyArray<string>) => Promise<number>
@@ -356,22 +357,19 @@ async function dispatch_command(rest: ReadonlyArray<string>): Promise<number> {
 	return await report_dispatch(await lane_dispatch.dispatch_child(issue), issue)
 }
 
-// Each valid argument is an issue number; any non-number stops parsing and triggers usage.
-function parse_issues(rest: ReadonlyArray<string>): ReadonlyArray<string> | undefined {
-	if (rest.length === 0) return undefined
-	const issues = rest.filter((value) => lane_await.ISSUE_PATTERN.test(value))
-
-	return issues.length === rest.length ? issues : undefined
-}
-
 // The completed issue number goes to standard output so `N=$(pnpm josh lane:await ...)` captures
-// which child finished without parsing stderr.
+// which child finished without parsing stderr. `--owner` reclaims the carry record for a resumed
+// conversation before the wait (`run-carry-reclaim.ts`).
 async function await_command(rest: ReadonlyArray<string>): Promise<number> {
-	const issues = parse_issues(rest)
+	const parsed = lane_await.parse_arguments(rest)
 
-	if (issues === undefined) return report_usage()
+	if (parsed === undefined) return report_usage()
+
+	if (parsed.owner !== undefined) {
+		await run_carry_reclaim.reclaim_carry(run_carry.owner_of(parsed.owner))
+	}
 
-	const completed = await lane_await.wait_for_any(issues)
+	const completed = await lane_await.wait_for_any(parsed.issues)
 
 	console.info(completed)
 

package/scripts/lines/bytes-command.ts

@@ -4,6 +4,7 @@ import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { document_byte_budget } from '#scripts/document/document-byte-budget'
 import { entry_read_budget } from '#scripts/document/entry-read-budget'
+import { resident_budget } from '#scripts/document/resident-budget'
 
 // The package root, resolved from this file rather than the caller's working directory.
 const REPO_ROOT = fileURLToPath(new URL('../../', import.meta.url))
@@ -75,14 +76,40 @@ function normalized_path(argument: string): string {
 	return argument.startsWith('./') ? argument.slice('./'.length) : argument
 }
 
+function remaining_phrase(remaining: number): string {
+	return remaining < 0 ? `over by ${(-remaining).toString()}` : `${remaining.toString()} left`
+}
+
+// The resident document is held by a fixed limit rather than a block ratchet, and loosening it is
+// Tier C, so its row names the headroom or the overage but never a value to raise it to
+// (joshuafolkken/kit#3171).
+function resident_row(status: DocumentStatus): string {
+	const counts = `${status.current.toString()}/${status.recorded.toString()} bytes`
+
+	return `${status.path}${ROW_GAP}${counts} · ${remaining_phrase(status.remaining)}`
+}
+
+function is_resident(relative_path: string): boolean {
+	return resident_budget.limit_bytes_for(relative_path) !== undefined
+}
+
+function recorded_for(relative_path: string): number | undefined {
+	return (
+		resident_budget.limit_bytes_for(relative_path) ??
+		document_byte_budget.recorded_bytes_for(relative_path)
+	)
+}
+
 function argument_row(argument: string, root: string = REPO_ROOT): string {
 	const relative_path = normalized_path(argument)
-	const recorded = document_byte_budget.recorded_bytes_for(relative_path)
+	const recorded = recorded_for(relative_path)
 
 	if (recorded === undefined) return `${relative_path}${ROW_GAP}${NOT_BUDGETED}`
 	if (!existsSync(path.join(root, relative_path))) return `${relative_path}${ROW_GAP}${NOT_A_FILE}`
 
-	return status_row(status_of(relative_path, recorded, root))
+	const status = status_of(relative_path, recorded, root)
+
+	return is_resident(relative_path) ? resident_row(status) : status_row(status)
 }
 
 // A document is "near its ceiling" once less than this is left before its recorded block ceiling —
@@ -118,10 +145,6 @@ function entry_status_of(entry: string, recorded: number): EntryStatus {
 	return { entry, current, recorded, remaining }
 }
 
-function remaining_phrase(remaining: number): string {
-	return remaining < 0 ? `over by ${(-remaining).toString()}` : `${remaining.toString()} left`
-}
-
 // The primary budget, one row per entry: the total each workflow entry reads against its recorded
 // ceiling and the headroom left — printed on every scan, so the main budget is no longer a number the
 // gate reveals only when it fails (joshuafolkken/kit#2271).

package/scripts/observations/observation-ledger-line.ts

@@ -1,4 +1,4 @@
-// The observation ledger's line grammar (`.claude/skills/workflow-commands/observation-filing.md`)
+// The observation ledger's line grammar (`.claude/skills/workflow-commands/observation-ledger.md`)
 // is fixed — `- k:<slug> | d<n> | <YYYY-MM-DD> | <where> | <what>` — but the path was collected in
 // `observation-ledger.ts` without a line ever being parsed, so a malformed append rode a flush
 // through unremarked. This validates a ledger entry line and reports why a broken one is broken

package/scripts/release/github-release-environment.ts

@@ -37,6 +37,7 @@ function read_release_input(environment: Environment): ReleaseInput {
 			start_tag: optional(environment['RELEASE_START_TAG']),
 			workflow: optional(environment['RELEASE_WORKFLOW']),
 			jobs: job_names(environment['RELEASE_JOBS']),
+			await_publish: environment['RELEASE_AWAIT_PUBLISH'] === 'true',
 		},
 	}
 }

package/scripts/release/github-release.ts

@@ -15,7 +15,12 @@ const POLL_INTERVAL_MS = 30_000
 const MAX_WAIT_ATTEMPTS = 120
 const RELEASE_SCHEMA = z.object({ tag_name: z.string().min(1) })
 const NOTES_SCHEMA = z.object({ name: z.string().min(1), body: z.string().min(1) })
-const RUN_SCHEMA = z.object({ id: z.number(), display_title: z.string() })
+const RUN_SCHEMA = z.object({
+	id: z.number(),
+	display_title: z.string(),
+	status: z.string().optional(),
+	conclusion: z.string().nullable().optional(),
+})
 const JOB_SCHEMA = z.object({
 	name: z.string(),
 	status: z.string(),
@@ -26,15 +31,19 @@ const JOBS_SCHEMA = z.object({ jobs: z.array(JOB_SCHEMA) })
 
 type ReleaseRequest = (url: string, init: RequestInit) => Promise<Response>
 type Wait = () => Promise<void>
+type PollState = 'ready' | 'failed' | 'pending'
 
 // What differs between repositories. `start_tag` is the last tag that predates automatic releases;
 // without it the latest existing release is the floor. `workflow` names the publish workflow whose
 // failed run lets a lower tag be skipped, and `jobs` the jobs in it that count (empty: every job).
+// `await_publish` holds the tag's own release until its run in that workflow has succeeded, for a
+// release started beside the publication rather than from inside it.
 interface ReleaseSettings {
 	repository: string
 	start_tag?: string | undefined
 	workflow?: string | undefined
 	jobs?: ReadonlyArray<string> | undefined
+	await_publish?: boolean | undefined
 }
 
 interface PublishOptions extends ReleaseSettings {
@@ -56,7 +65,14 @@ interface Ladder {
 	tags: ReadonlyArray<string>
 	floor: string | undefined
 	fallback?: () => Promise<string>
+	budget: Budget
+}
+
+// One allowance shared by every wait a release makes: waiting for its own publication and then for
+// lower tags' releases must end inside the job's `timeout-minutes` together, not each on its own.
+interface Budget {
 	wait: Wait
+	remaining: number
 }
 
 function request_options(token: string, method: string, body?: object): RequestInit {
@@ -130,13 +146,22 @@ function is_failed_job(job: z.infer<typeof JOB_SCHEMA>, names: ReadonlyArray<str
 	return names.some((name) => job.name === name || job.name.startsWith(`${name} /`))
 }
 
+async function publish_run(
+	client: Client,
+	workflow_name: string,
+	tag: string,
+): Promise<z.infer<typeof RUN_SCHEMA> | undefined> {
+	const workflow = encodeURIComponent(workflow_name)
+	const runs_response = await api_get(client, `/actions/workflows/${workflow}/runs?per_page=100`)
+	const runs = RUNS_SCHEMA.parse(await read_response(runs_response)).workflow_runs
+
+	return runs.find((item) => item.display_title === `Publish ${tag}`)
+}
+
 async function failed_publication(client: Client, tag: string): Promise<boolean> {
 	if (client.workflow === undefined) return false
 
-	const workflow = encodeURIComponent(client.workflow)
-	const runs_response = await api_get(client, `/actions/workflows/${workflow}/runs?per_page=100`)
-	const runs = RUNS_SCHEMA.parse(await read_response(runs_response)).workflow_runs
-	const run = runs.find((item) => item.display_title === `Publish ${tag}`)
+	const run = await publish_run(client, client.workflow, tag)
 	if (!run) return false
 
 	const jobs_response = await api_get(client, `/actions/runs/${String(run.id)}/jobs?per_page=100`)
@@ -149,24 +174,72 @@ async function default_wait(): Promise<void> {
 	await setTimeout(POLL_INTERVAL_MS)
 }
 
-async function release_state(client: Client, tag: string): Promise<'ready' | 'failed' | 'pending'> {
+async function release_state(client: Client, tag: string): Promise<PollState> {
 	if (await existing_release(client, tag)) return 'ready'
 	if (await failed_publication(client, tag)) return 'failed'
 
 	return 'pending'
 }
 
-async function wait_for_release(client: Client, tag: string, wait: Wait): Promise<boolean> {
-	for (let attempt = 0; attempt < MAX_WAIT_ATTEMPTS; attempt += 1) {
+// A run not listed yet is pending too: the announcement that starts this release also starts the
+// publication, so the release can ask before GitHub has queued that run.
+async function publication_state(
+	client: Client,
+	workflow: string,
+	tag: string,
+): Promise<PollState> {
+	const run = await publish_run(client, workflow, tag)
+	if (run?.status !== 'completed') return 'pending'
+
+	return run.conclusion === 'success' ? 'ready' : 'failed'
+}
+
+async function poll(
+	read: () => Promise<PollState>,
+	budget: Budget,
+	subject: string,
+): Promise<boolean> {
+	while (budget.remaining > 0) {
 		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
-		const state = await release_state(client, tag)
+		const state = await read()
 		if (state !== 'pending') return state === 'ready'
 
+		budget.remaining -= 1
 		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
-		await wait()
+		await budget.wait()
 	}
 
-	throw new Error(`Timed out waiting for previous GitHub Release ${tag}`)
+	throw new Error(`Timed out waiting for ${subject}`)
+}
+
+async function wait_for_release(client: Client, tag: string, budget: Budget): Promise<boolean> {
+	return await poll(
+		async () => await release_state(client, tag),
+		budget,
+		`previous GitHub Release ${tag}`,
+	)
+}
+
+async function wait_for_publication(client: Client, tag: string, budget: Budget): Promise<boolean> {
+	const { workflow } = client
+	if (workflow === undefined) throw new Error('Waiting for the publication needs RELEASE_WORKFLOW')
+
+	return await poll(
+		async () => await publication_state(client, workflow, tag),
+		budget,
+		`Publish ${tag}`,
+	)
+}
+
+async function is_publication_ready(
+	client: Client,
+	tag: string,
+	options: PublishOptions,
+	budget: Budget,
+): Promise<boolean> {
+	if (options.await_publish !== true) return true
+
+	return await wait_for_publication(client, tag, budget)
 }
 
 async function ladder_end(ladder: Ladder): Promise<string | undefined> {
@@ -184,7 +257,7 @@ async function baseline_tag(
 	if (ladder.floor === undefined) return prior
 	if (!prior) return await ladder_end(ladder)
 
-	return (await wait_for_release(client, prior, ladder.wait))
+	return (await wait_for_release(client, prior, ladder.budget))
 		? prior
 		: await baseline_tag(client, prior, ladder)
 }
@@ -195,16 +268,19 @@ function assert_older(previous: string | undefined, tag: string): void {
 	}
 }
 
-async function build_ladder(client: Client, options: PublishOptions): Promise<Ladder> {
+async function build_ladder(
+	client: Client,
+	options: PublishOptions,
+	budget: Budget,
+): Promise<Ladder> {
 	const tags = options.tags ?? []
-	const wait = options.wait ?? default_wait
 	const { start_tag } = options
 
 	if (start_tag !== undefined) {
-		return { tags, wait, floor: start_tag, fallback: async () => await previous_tag(client) }
+		return { tags, budget, floor: start_tag, fallback: async () => await previous_tag(client) }
 	}
 
-	return { tags, wait, floor: await latest_release(client) }
+	return { tags, budget, floor: await latest_release(client) }
 }
 
 async function generate_notes(
@@ -252,6 +328,10 @@ function create_client(request: ReleaseRequest, token: string, settings: Release
 	}
 }
 
+function create_budget(options: PublishOptions): Budget {
+	return { wait: options.wait ?? default_wait, remaining: MAX_WAIT_ATTEMPTS }
+}
+
 async function publish(
 	request: ReleaseRequest,
 	token: string,
@@ -263,7 +343,13 @@ async function publish(
 	const client = create_client(request, token, options)
 	if (await existing_release(client, tag)) return 'already-published'
 
-	const previous = await baseline_tag(client, tag, await build_ladder(client, options))
+	const budget = create_budget(options)
+
+	if (!(await is_publication_ready(client, tag, options, budget))) {
+		return `skipped ${tag}: Publish ${tag} did not succeed`
+	}
+
+	const previous = await baseline_tag(client, tag, await build_ladder(client, options, budget))
 
 	assert_older(previous, tag)
 	await create_release(client, tag, previous)