@joshuafolkken/kit 1.1050.0 → 1.1094.0

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

@@ -1,6 +1,8 @@
-import { EPIC_LABEL, has_label_name } from '#scripts/git/issue-labels'
+import { EPIC_LABEL, has_label_name, NEEDS_DECISION_LABEL } from '#scripts/issue/issue-labels'
+import type { IssueState } from '#scripts/issue/issue-state'
 import { issue_state_cli } from '#scripts/issue/issue-state-cli'
 import type { RunCarry } from '#scripts/run/run-carry'
+import type { MergeResult } from '#scripts/run/run-merge-cli'
 import { backlog_budget } from './backlog-budget'
 import type { DriveState, OfferRead } from './backlog-drive'
 import { backlog_drive_named } from './backlog-drive-named'
@@ -44,6 +46,15 @@ function budget_offer(
 	}
 }
 
+// The outcome a named issue has already reached without this run dispatching it: closed is merged, and
+// a `needs-decision` park waits on a person, so re-dispatching it only repeats the stop it parked on
+// (joshuafolkken/kit#2965). Either is booked done rather than offered.
+function settled_outcome(state: IssueState): MergeResult['outcome'] | undefined {
+	if (state.state.toUpperCase() === 'CLOSED') return 'merged'
+
+	return has_label_name(state.labels, NEEDS_DECISION_LABEL) ? 'parked' : undefined
+}
+
 async function classify(issue: string, named: OfferRead, owner: string): Promise<OfferRead> {
 	const result = await issue_state_cli.read_issue(issue)
 
@@ -51,8 +62,10 @@ async function classify(issue: string, named: OfferRead, owner: string): Promise
 		return { verdict: 'issue-state', issues: [], retries: NO_RETRIES }
 	}
 
-	if (result.state.state.toUpperCase() === 'CLOSED') {
-		await backlog_drive_named.mark_done(issue, { outcome: 'merged', code: 0, token: 'none' }, owner)
+	const outcome = settled_outcome(result.state)
+
+	if (outcome !== undefined) {
+		await backlog_drive_named.mark_done(issue, { outcome, code: 0, token: 'none' }, owner)
 
 		return { verdict: 'wait', issues: [], retries: NO_RETRIES }
 	}

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

@@ -1,4 +1,4 @@
-import { has_label_name, NEEDS_DECISION_LABEL } from '#scripts/git/issue-labels'
+import { has_label_name, NEEDS_DECISION_LABEL } from '#scripts/issue/issue-labels'
 import { issue_state_cli } from '#scripts/issue/issue-state-cli'
 import { run_carry, type RunCarry } from '#scripts/run/run-carry'
 import type { RunEvent } from '#scripts/run/run-event-stream'
@@ -94,6 +94,7 @@ async function reconcile(
 	for (const issue of completed) {
 		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)
 	}
 }

package/scripts/backlog/backlog-drive.ts

@@ -16,6 +16,9 @@
 // **Everything it touches is a port**, the pattern `run-wake-loop.ts` set, so the sequencing is pinned
 // without a process, a network or a clock.
 
+import type { LaunchOutcome } from '#scripts/lane/lane-launch-cli'
+import type { MergeResult } from '#scripts/run/run-merge-cli'
+
 const RUN_VERDICT = 'run'
 const STOP_VERDICT = 'stop'
 // The `run:merge` tokens that end the loop at once: a hand-off, a person's stop, the environment down,
@@ -32,6 +35,7 @@ const IMMEDIATE_TOKENS: ReadonlySet<string> = new Set([
 // and the children still in flight are collected before the loop ends (joshuafolkken/kit#2881).
 const HANDOFF_TOKENS: ReadonlySet<string> = new Set([...IMMEDIATE_TOKENS, STOP_VERDICT])
 const RESUMED_TOKEN = 'resumed'
+const MERGED_OUTCOME = 'merged'
 const WATCH_VERDICT = 'watch'
 // The verdicts the loop acts on without the parent. Any other is handed back as it was printed.
 const KNOWN_VERDICTS: ReadonlySet<string> = new Set([
@@ -41,6 +45,9 @@ const KNOWN_VERDICTS: ReadonlySet<string> = new Set([
 	'wait',
 ])
 const NO_RETRIES = 0
+const NO_FREE_LANES = 0
+const LAUNCHED = 'launched'
+const UNOPENED = 'unopened'
 
 interface OfferRead {
 	verdict: string
@@ -57,7 +64,9 @@ interface OfferRead {
 interface DriveState {
 	// The children this run has in flight — seeded from the open lanes, so a restarted loop resumes them.
 	in_flight: Array<string>
-	// Every child collected, fed back to `backlog:offer` because GitHub closes a merged issue late.
+	// Every child merged, fed back to `backlog:offer` because GitHub closes a merged issue late. A parked
+	// child is left out: its labels classify it, so one a person released is offered again
+	// (joshuafolkken/kit#3041).
 	exclude: Array<string>
 	// When the run last did something, handed to `backlog:budget` as `--active`.
 	active: string
@@ -80,14 +89,20 @@ interface DriveEnd {
 	is_finish?: boolean | undefined
 }
 
+type Collected = Pick<MergeResult, 'token' | 'outcome'>
+
 interface DrivePorts {
 	// Whether a child's process has confirmed-ended — `lane:await`'s re-confirmed check in production.
 	is_finished: (issue: string) => boolean
-	// `run:merge <N>`'s first stdout token.
-	merge: (issue: string) => Promise<string>
+	// `run:merge <N>`'s first stdout token and the outcome it handled the child as.
+	merge: (issue: string) => Promise<Collected>
 	// `backlog:offer`'s answer for the state, or `undefined` when it exited non-zero.
 	offer: (state: DriveState) => Promise<OfferRead | undefined>
-	launch: (issue: string) => Promise<boolean>
+	// Where `lane:launch`'s chain ended — `launched`, `unopened` (no lane taken) or `failed` (one taken).
+	launch: (issue: string) => Promise<LaunchOutcome['kind']>
+	// The lanes free right now — `backlog_ready.drive_free_lane_count` in production, the limit less the
+	// open lanes.
+	free_lanes: () => Promise<number>
 	now: () => Date
 }
 
@@ -150,29 +165,40 @@ function merge_stopped(issue: string, state: DriveState): DriveState {
 	}
 }
 
-// The child collected and excluded, and — unless its cut was resumed in place — out of flight.
+// Only a merged child is excluded: `backlog:next` may still read it OPEN. Any other is classified by
+// its labels, so excluding it would hide a child a person released for the rest of the process.
+function excluded(issue: string, outcome: Collected['outcome'], state: DriveState): Array<string> {
+	if (outcome !== MERGED_OUTCOME || state.exclude.includes(issue)) return state.exclude
+
+	return [...state.exclude, issue]
+}
+
+// The child collected, and — unless its cut was resumed in place — out of flight.
 function collected_state(
 	issue: string,
-	token: string,
+	collected: Collected,
 	state: DriveState,
 	active: string,
 ): DriveState {
 	const in_flight =
-		token === RESUMED_TOKEN ? state.in_flight : state.in_flight.filter((item) => item !== issue)
-	const exclude = state.exclude.includes(issue) ? state.exclude : [...state.exclude, issue]
+		collected.token === RESUMED_TOKEN
+			? state.in_flight
+			: state.in_flight.filter((item) => item !== issue)
+	const exclude = excluded(issue, collected.outcome, state)
 
 	return { ...state, in_flight, exclude, active }
 }
 
 // One finished child: handed back on an immediate token, otherwise collected.
 async function collect(issue: string, state: DriveState, ports: DrivePorts): Promise<PassResult> {
-	const token = await ports.merge(issue)
+	const collected = await ports.merge(issue)
+	const { token } = collected
 
 	// An empty first line is a `run:merge` that failed before printing one: never read as a collection.
 	if (token === '') return ended('merge', state, undefined, issue)
 	if (IMMEDIATE_TOKENS.has(token)) return ended('merge', state, token, issue)
 
-	const next = collected_state(issue, token, state, ports.now().toISOString())
+	const next = collected_state(issue, collected, state, ports.now().toISOString())
 
 	return { kind: 'continue', state: token === STOP_VERDICT ? merge_stopped(issue, next) : next }
 }
@@ -182,6 +208,7 @@ async function collect_finished(state: DriveState, ports: DrivePorts): Promise<P
 	let current = state
 
 	for (const issue of finished) {
+		// eslint-disable-next-line no-await-in-loop -- each collect starts from the state the previous one returned
 		const result = await collect(issue, current, ports)
 
 		if (result.kind === 'end') return { ...result, state: current }
@@ -192,22 +219,55 @@ async function collect_finished(state: DriveState, ports: DrivePorts): Promise<P
 	return { kind: 'continue', state: current }
 }
 
+// A `lane:open` refused with every lane taken is a wait, not a judgement (joshuafolkken/kit#3027): the
+// next offer after a lane frees retries it. A step failing after the lane opened is always handed back —
+// that lane holds the last seat itself, so the free count would read the failure as a full pool.
+async function refused(
+	issue: string,
+	outcome: LaunchOutcome['kind'],
+	state: DriveState,
+	ports: DrivePorts,
+): Promise<PassResult> {
+	if (outcome !== UNOPENED) return ended('launch', state, undefined, issue)
+	if ((await ports.free_lanes()) <= NO_FREE_LANES) return { kind: 'continue', state }
+
+	return ended('launch', state, undefined, issue)
+}
+
+// **No more launches than free lanes** (joshuafolkken/kit#3027). `backlog:offer` lists every ready issue
+// without reading the lanes, so launching all of them overran `JOSH_LANE_LIMIT` until `lane:open` ran
+// out of seats. The free count is read once, before the first launch, because every launch here opens
+// a lane the count would otherwise have to be told about.
+//
+// **Only a launch is activity** (joshuafolkken/kit#3027): a pass that started nothing — every lane taken
+// — keeps `active` where it was, or the once-a-minute offer would restart the idle budget for good.
+function launched(state: DriveState, in_flight: Array<string>, ports: DrivePorts): DriveState {
+	if (in_flight.length === state.in_flight.length) return { ...state, in_flight }
+
+	return { ...state, in_flight, active: ports.now().toISOString() }
+}
+
 async function launch_all(
 	issues: ReadonlyArray<string>,
 	state: DriveState,
 	ports: DrivePorts,
 ): Promise<PassResult> {
 	const in_flight = [...state.in_flight]
+	const free = await ports.free_lanes()
 
-	for (const issue of issues) {
-		const is_launched = await ports.launch(issue)
+	for (const issue of issues.slice(0, free)) {
+		// eslint-disable-next-line no-await-in-loop -- lanes launch in order and the first refusal ends the pass
+		const outcome = await ports.launch(issue)
 
-		if (!is_launched) return ended('launch', { ...state, in_flight }, undefined, issue)
+		if (outcome !== LAUNCHED) {
+			// eslint-disable-next-line no-await-in-loop -- lanes launch in order and the first refusal ends the pass
+			return await refused(issue, outcome, launched(state, in_flight, ports), ports)
+		}
 
 		in_flight.push(issue)
 	}
 
-	return { kind: 'continue', state: { ...state, in_flight, active: ports.now().toISOString() } }
+	return { kind: 'continue', state: launched(state, in_flight, ports) }
 }
 
 // A watch with nothing in flight is the drain: `run:step` owes the retrospective there, so it is the
@@ -337,7 +397,9 @@ async function run_loop(
 	let step = await loop_step(first, config, ports)
 
 	while (step.kind === 'next') {
+		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
 		await ports.sleep(config.poll_ms)
+		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
 		step = await loop_step(step.run, config, ports)
 	}
 
@@ -348,10 +410,8 @@ async function run_loop(
 
 const backlog_drive = {
 	HANDOFF_TOKENS,
-	collect,
 	initial_state,
 	merge_stopped,
-	on_verdict,
 	run_loop,
 	run_pass,
 }

package/scripts/backlog/backlog-named.ts

@@ -141,9 +141,6 @@ function epic_item_outcome(
 }
 
 const backlog_named = {
-	BACKLOG_KIND,
-	END_KIND,
-	NAMED_KIND,
 	NOTHING_TO_RUN,
 	after_failure,
 	epic_item_outcome,

package/scripts/backlog/backlog-next.ts

@@ -9,8 +9,9 @@ import { epic_next } from '#scripts/epic/epic-next'
 import { epic_next_read, type EpicRead } from '#scripts/epic/epic-next-read'
 import type { EpicView } from '#scripts/epic/epic-next-views'
 import { epic_report, type EpicNextResult, type EpicVerdict } from '#scripts/epic/epic-report'
+import { epic_solo_stale } from '#scripts/epic/epic-solo-stale'
 import { epic_triage, type TriageVerdict } from '#scripts/epic/epic-triage'
-import { git_gh_command } from '#scripts/git/git-gh-command'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
 import { issue_citation } from '#scripts/rules/issue-citation'
 import { backlog_defect_priority } from './backlog-defect-priority'
@@ -294,7 +295,13 @@ async function gate_solo(result: EpicNextResult, context: PoolContext): Promise<
 	if (result.verdict !== 'run') return result
 
 	const { repo } = context
-	const read = await epic_busy.read_repository(repo)
+	const { read, notice } = await epic_solo_stale.release(
+		await epic_busy.read_repository(repo),
+		repo,
+	)
+
+	if (notice !== undefined) console.error(notice)
+
 	const gated = backlog_rank.gate(result, read, repo, standalone_keys(context))
 
 	if (gated.notice !== undefined) console.error(gated.notice)
@@ -410,23 +417,10 @@ const backlog_next = {
 	RETRY_MESSAGE,
 	READ_FAILURES,
 	VERDICT_TOKENS,
-	tokens_of,
-	warn_epic_gap,
-	warn_gaps,
-	report,
-	combine,
-	views_from,
 	resolve,
 	standalone_keys,
-	is_transport_failure,
-	report_retry,
-	report_triage,
 	context_of,
-	answer_pool,
-	report_none,
-	answer,
 	run,
-	main,
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))

package/scripts/backlog/backlog-offer-cli.ts

@@ -262,16 +262,11 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 
 const backlog_offer_cli = {
 	JSON_KEY,
-	USAGE,
 	budget_argv,
 	counts_of,
-	emit,
-	main,
-	mark_drain,
 	next_argv,
 	read_values,
 	run,
-	to_tokens,
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))

package/scripts/backlog/backlog-plan-cli.ts

@@ -3,7 +3,7 @@ import { fileURLToPath } from 'node:url'
 import { auto_ok_cli } from '#scripts/auto-ok/auto-ok-cli'
 import { epic_index } from '#scripts/epic/epic-index'
 import type { EpicNextResult } from '#scripts/epic/epic-report'
-import { git_gh_command } from '#scripts/git/git-gh-command'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { read_json_listing } from '#scripts/git/parse-json-array'
 import { open_issue_schema, type OpenIssueData } from '#scripts/git/schemas'
 import { run_invocation } from '#scripts/run/run-invocation'
@@ -263,13 +263,7 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 const backlog_plan_cli = {
 	OPEN_TRUNCATED_MESSAGE,
 	OPEN_UNREADABLE_MESSAGE,
-	USAGE,
 	WAVES_WITH_NAMED_MESSAGE,
-	classify,
-	fetch_open,
-	main,
-	print_plan,
-	report,
 	run,
 }
 

package/scripts/backlog/backlog-plan.ts

@@ -3,7 +3,7 @@ import type { IssueReference } from '#scripts/epic/epic-reference'
 import { epic_report, type EpicNextResult } from '#scripts/epic/epic-report'
 import { epic_solo } from '#scripts/epic/epic-solo'
 import { epic_triage } from '#scripts/epic/epic-triage'
-import { has_label_name, IN_PROGRESS_LABEL, RUN_SOLO_LABEL } from '#scripts/git/issue-labels'
+import { has_label_name, IN_PROGRESS_LABEL, RUN_SOLO_LABEL } from '#scripts/issue/issue-labels'
 import type { OutOfScopeRow } from './backlog-scope'
 
 // The plan a person reads before a `backlogrun` starts (joshuafolkken/kit#1652).

package/scripts/backlog/backlog-pool.ts

@@ -5,14 +5,14 @@ import { epic_index } from '#scripts/epic/epic-index'
 import { epic_issue } from '#scripts/epic/epic-issue'
 import type { EpicView } from '#scripts/epic/epic-next-views'
 import { epic_outside_blocker } from '#scripts/epic/epic-outside-blocker'
-import { git_next_issues } from '#scripts/git/git-next-issues'
+import type { OpenIssueData } from '#scripts/git/schemas'
+import { git_next_issues } from '#scripts/issue/git-next-issues'
 import {
 	ALREADY_DONE_LABEL,
 	EPIC_LABEL,
 	has_any_label,
 	NEEDS_DECISION_LABEL,
-} from '#scripts/git/issue-labels'
-import type { OpenIssueData } from '#scripts/git/schemas'
+} from '#scripts/issue/issue-labels'
 
 // The candidate pool `josh backlog:next` answers from (joshuafolkken/kit#1630).
 //
@@ -328,14 +328,11 @@ const backlog_pool = {
 	standalone_keys,
 	drop_excluded,
 	epic_classification,
-	is_epic_row,
-	keys_of,
 	merge_classifications,
 	opted_in_epics,
 	standalone_rows,
 	to_child,
 	to_children,
-	unique_children,
 }
 
 export { backlog_pool }

package/scripts/backlog/backlog-rank.ts

@@ -3,7 +3,7 @@ import { epic_graph, type EpicChild } from '#scripts/epic/epic-graph'
 import { epic_rank } from '#scripts/epic/epic-rank'
 import type { EpicNextResult } from '#scripts/epic/epic-report'
 import { epic_solo, type SoloGate, type SoloSelection } from '#scripts/epic/epic-solo'
-import { git_next_issues } from '#scripts/git/git-next-issues'
+import { git_next_issues } from '#scripts/issue/git-next-issues'
 
 // What the backlog offers, in the order it is decided (joshuafolkken/kit#2928): rank, then the
 // `run:solo` gate, then the cap. `backlog:next` and `backlog:plan --waves` both call `select`, so the
@@ -100,7 +100,7 @@ function gate(
 	)
 }
 
-const backlog_rank = { everything_in, gate, rank, rank_result, select }
+const backlog_rank = { everything_in, gate, rank_result, select }
 
 export { backlog_rank }
 export type { OfferInput }

package/scripts/backlog/backlog-ready.ts

@@ -21,6 +21,13 @@ interface ReadyPorts {
 	ready_issues: () => Promise<ReadonlyArray<string>>
 }
 
+async function free_under(limit: number): Promise<number> {
+	const lanes = await lane_registry.list_lanes()
+	const live = lanes.filter((lane) => !lane.is_stranded).length
+
+	return lane_capacity.free_lanes(limit, live)
+}
+
 // Free lanes right now: the limit less the live lanes. An unreadable limit reads as no free lane — the
 // safe direction, since both the stall and the ready line need a free lane and reporting one that is
 // not there is the false positive neither may raise.
@@ -35,10 +42,18 @@ async function free_lane_count(): Promise<number> {
 
 	if (limit.kind !== 'limit') return NO_FREE
 
-	const lanes = await lane_registry.list_lanes()
-	const live = lanes.filter((lane) => !lane.is_stranded).length
+	return await free_under(limit.limit)
+}
+
+// **The drive's count throws on an unreadable limit** (joshuafolkken/kit#3027). The drive launches no
+// more than this count, so the safe-direction zero above would leave it launching nothing and reporting
+// nothing for good; a bad setting is the hard error `lane_capacity` says it is, ending the drive loudly.
+async function drive_free_lane_count(): Promise<number> {
+	const limit = lane_capacity.lane_limit()
+
+	if (limit.kind !== 'limit') throw new Error(limit.problem)
 
-	return lane_capacity.free_lanes(limit.limit, live)
+	return await free_under(limit.limit)
 }
 
 // **A `--only` run has no pool to drain** (joshuafolkken/kit#2472). `backlog:next` lists the opted-in
@@ -135,6 +150,7 @@ const backlog_ready = {
 	read_backlog_next,
 	print_offer_hint,
 	free_lane_count,
+	drive_free_lane_count,
 	drains_pool,
 	print_ready_line,
 	read_ready,

package/scripts/backlog/backlog-scope.ts

@@ -1,6 +1,6 @@
 import type { EpicNextResult } from '#scripts/epic/epic-report'
-import { AUTO_OK_LABEL, EPIC_LABEL, has_any_label } from '#scripts/git/issue-labels'
 import type { OpenIssueData } from '#scripts/git/schemas'
+import { AUTO_OK_LABEL, EPIC_LABEL, has_any_label } from '#scripts/issue/issue-labels'
 
 // Which open issues the backlog will not run, and why (joshuafolkken/kit#1652).
 //
@@ -135,8 +135,6 @@ const backlog_scope = {
 	OPTED_IN_UNPLACED_REASON,
 	open_numbers_of,
 	out_of_scope,
-	planned_numbers,
-	reason_for,
 	titles_of,
 }
 

package/scripts/backlog/backlog-stalled-detect.ts

@@ -1,4 +1,4 @@
-import { telegram_notify } from '#scripts/git/telegram-notify'
+import { telegram_notify } from '#scripts/notify/telegram-notify'
 import { run_event_stream, type RunEvent } from '#scripts/run/run-event-stream'
 import { run_event_stream_emit } from '#scripts/run/run-event-stream-emit'
 import { backlog_ready, type ReadyPorts } from './backlog-ready'
@@ -137,7 +137,7 @@ async function run_stall_check(ready: ReadyPorts = backlog_ready.DEFAULT_PORTS):
 	}
 }
 
-const backlog_stalled_detect = { DEFAULT_PORTS, detect_and_report, gather, report, run_stall_check }
+const backlog_stalled_detect = { detect_and_report, run_stall_check }
 
 export { backlog_stalled_detect }
 export type { DetectPorts }

package/scripts/backlog/backlog-stalled.ts

@@ -118,7 +118,6 @@ const backlog_stalled = {
 	count_ready_tokens,
 	describe,
 	dispatch_age_ms,
-	is_stalled,
 	needs_triage,
 	ready_tokens,
 }

package/scripts/backlog/backlog-waves.ts

@@ -4,7 +4,11 @@ import { epic_cross_repo } from '#scripts/epic/epic-cross-repo'
 import { epic_graph, type EpicChild } from '#scripts/epic/epic-graph'
 import { epic_outside_blocker } from '#scripts/epic/epic-outside-blocker'
 import { epic_report, type EpicNextResult } from '#scripts/epic/epic-report'
-import { has_label_name, IN_PROGRESS_LABEL, NEEDS_DECISION_LABEL } from '#scripts/git/issue-labels'
+import {
+	has_label_name,
+	IN_PROGRESS_LABEL,
+	NEEDS_DECISION_LABEL,
+} from '#scripts/issue/issue-labels'
 import { backlog_plan, type PlanContext } from './backlog-plan'
 import { backlog_rank } from './backlog-rank'
 
@@ -171,7 +175,6 @@ function format_waves(
 const backlog_waves = {
 	HEADING_ASSUMPTION,
 	NEEDS_DECISION_NOTE,
-	NOT_REACHED_NOTE,
 	PARALLEL_NOTE,
 	UNREACHED_HEADING,
 	build,

package/scripts/behavior/behavior-cli.ts

@@ -81,7 +81,7 @@ function run(cwd: string = process.cwd()): number {
 	return file === undefined ? report_no_transcript() : check_session(file)
 }
 
-const behavior_cli = { LABEL, check_session, current_session, run }
+const behavior_cli = { check_session, run }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) process.exitCode = run()
 

package/scripts/build/build-codex-hooks.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env tsx
+import { readFileSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { codex_hooks } from '#scripts/agent/codex-hooks'
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..')
+const CLAUDE_SETTINGS = path.join(REPO_ROOT, '.claude', 'settings.json')
+const CODEX_HOOKS = path.join(REPO_ROOT, '.codex', 'hooks.json')
+
+// Regenerate `.codex/hooks.json` from `.claude/settings.json` (joshuafolkken/kit#2997). The output is
+// committed rather than gitignored: Codex reads it straight from a fresh clone of kit, before any
+// build has run, and `josh init` / `josh sync` copy it to consumers from the package.
+function build_codex_hooks(): string {
+	writeFileSync(CODEX_HOOKS, codex_hooks.codex_hooks_text(readFileSync(CLAUDE_SETTINGS, 'utf8')))
+
+	return CODEX_HOOKS
+}
+
+function main(): void {
+	console.info(`  ✔ ${build_codex_hooks()} built`)
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) main()
+
+export { build_codex_hooks, CLAUDE_SETTINGS, CODEX_HOOKS }