@joshuafolkken/kit 1.1471.0 → 1.1784.0

package/scripts/cost-runtime/cost-blocks.ts

@@ -1,4 +1,9 @@
 import { json_value } from '#scripts/lib/json-value'
+import {
+	transcript_record,
+	type TranscriptBlock,
+	type TranscriptContent,
+} from '#scripts/lib/transcript-record'
 import { z } from 'zod'
 
 // Reading the content blocks out of a session transcript.
@@ -18,27 +23,7 @@ import { z } from 'zod'
 const CONTENT_ITEM_SCHEMA = z.object({ text: z.string().nullish() })
 const RESULT_CONTENT_SCHEMA = z.union([z.string(), z.array(CONTENT_ITEM_SCHEMA)])
 
-// Every field is optional, including `type`. A required field would make one unexpected block fail
-// the whole array it sits in, and with it every other block on that line — an entire assistant turn
-// dropped from the table because one tool wrote a shape this reader had not seen. A block that
-// parses to nothing contributes nothing, which is the cost it should have.
-const BLOCK_SCHEMA = z.object({
-	type: z.string().nullish(),
-	text: z.string().nullish(),
-	name: z.string().nullish(),
-	input: z.unknown().nullish(),
-	content: RESULT_CONTENT_SCHEMA.nullish(),
-})
-
-const LINE_CONTENT_SCHEMA = z.union([z.string(), z.array(BLOCK_SCHEMA)])
-const MESSAGE_SCHEMA = z.object({ content: LINE_CONTENT_SCHEMA.nullish() })
-const CONTENT_LINE_SCHEMA = z.object({ type: z.string(), message: MESSAGE_SCHEMA.nullish() })
-
-type RawBlock = z.infer<typeof BLOCK_SCHEMA>
-
-const TEXT_TYPE = 'text'
-const TOOL_USE_TYPE = 'tool_use'
-const TOOL_RESULT_TYPE = 'tool_result'
+const { TEXT_TYPE, TOOL_USE_TYPE, TOOL_RESULT_TYPE } = transcript_record
 const BASH_TOOL = 'Bash'
 const COMMAND_KEY = 'command'
 
@@ -71,7 +56,7 @@ function split_bash_input(input: unknown): { command: string; rest: string } {
 	}
 }
 
-function to_tool_use(block: RawBlock): ContentBlock {
+function to_tool_use(block: TranscriptBlock): ContentBlock {
 	const tool_name = block.name ?? ''
 	const is_bash = tool_name === BASH_TOOL
 	const { command, rest } = is_bash
@@ -83,31 +68,33 @@ function to_tool_use(block: RawBlock): ContentBlock {
 
 // A tool result is either a plain string or a list of blocks. Only the textual items are counted:
 // an image block carries no text here, and inventing a size for it would put a made-up number in a
-// table whose whole purpose is to be compared against another run's.
-function result_text(content: string | ReadonlyArray<z.infer<typeof CONTENT_ITEM_SCHEMA>>): string {
-	if (typeof content === 'string') return content
-
-	return content.map((item) => item.text ?? '').join('')
+// table whose whole purpose is to be compared against another run's. A body of neither shape
+// contributes nothing rather than dropping the line it sits on.
+function result_text(content: unknown): string {
+	const parsed = RESULT_CONTENT_SCHEMA.safeParse(content)
+	if (!parsed.success) return ''
+	if (typeof parsed.data === 'string') return parsed.data
+
+	return parsed.data.map((item) => item.text ?? '').join('')
 }
 
 // Everything that is not a tool call: a result contributes its textual content, and anything else —
 // text, thinking, a block type this reader has never seen — contributes its `text`, which for
 // thinking is the empty string Claude Code writes there.
-function to_plain_block(block: RawBlock): ContentBlock {
+function to_plain_block(block: TranscriptBlock): ContentBlock {
 	const base = { type: block.type ?? '', tool_name: '', command: '' }
-	const text =
-		block.type === TOOL_RESULT_TYPE ? result_text(block.content ?? '') : (block.text ?? '')
+	const text = block.type === TOOL_RESULT_TYPE ? result_text(block.content) : (block.text ?? '')
 
 	return { ...base, text }
 }
 
-function to_block(block: RawBlock): ContentBlock {
+function to_block(block: TranscriptBlock): ContentBlock {
 	return block.type === TOOL_USE_TYPE ? to_tool_use(block) : to_plain_block(block)
 }
 
 // A user turn whose content is a bare string — the prompt itself, plus whatever a `UserPromptSubmit`
 // hook injected into it. Counted as text, which is what it is.
-function to_blocks(content: string | ReadonlyArray<RawBlock>): Array<ContentBlock> {
+function to_blocks(content: string | ReadonlyArray<TranscriptBlock>): Array<ContentBlock> {
 	if (typeof content === 'string') {
 		return [{ type: TEXT_TYPE, tool_name: '', command: '', text: content }]
 	}
@@ -116,13 +103,11 @@ function to_blocks(content: string | ReadonlyArray<RawBlock>): Array<ContentBloc
 }
 
 // A blank line, a line that is not JSON, and a line carrying no message content are one answer:
-// nothing to count. With `BLOCK_SCHEMA` accepting anything object-shaped, the only line lost whole
+// nothing to count. With the block schema accepting anything object-shaped, the only line lost whole
 // is one that is not JSON at all — which `cost-usage.ts` already counts as unparseable, so
 // reporting it again here would double one missing-data figure.
-function content_of(line: string): z.infer<typeof LINE_CONTENT_SCHEMA> | undefined {
-	const parsed = CONTENT_LINE_SCHEMA.safeParse(json_value.parse_or_undefined(line))
-
-	return parsed.success ? (parsed.data.message?.content ?? undefined) : undefined
+function content_of(line: string): TranscriptContent | undefined {
+	return transcript_record.parse(line)?.message?.content ?? undefined
 }
 
 function parse_line(line: string): Array<ContentBlock> {

package/scripts/cost-runtime/cost-cli.ts

@@ -1,5 +1,3 @@
-#!/usr/bin/env tsx
-import { fileURLToPath } from 'node:url'
 import { agent_role_profile, type AgentProvider } from '#scripts/agent/agent-role-profile'
 import { cli_flags } from '#scripts/lib/cli-flags'
 import { codex_usage } from './codex-usage'
@@ -20,7 +18,6 @@ import { transcript_cwd } from './transcript-cwd'
 // `backlogrun` / `halfrun` / `pre-gate-cut` ask, and the `josh time` run-timing report keeps the
 // hand-off aggregates used to compare the shared context-cut threshold.
 
-const ARGV_OFFSET = 2
 const FAILURE_EXIT_CODE = 1
 const USAGE = 'Usage: josh cost (--cut | --over <tokens-per-request>) [--path <dir>]'
 // The read-only verdict's third answer, beside `cost_verdict`'s over/under: a session that cannot be
@@ -29,6 +26,12 @@ const UNMEASURABLE_VERDICT = 'unmeasurable'
 
 type CostVerdict = ReturnType<typeof cost_verdict.classify> | typeof UNMEASURABLE_VERDICT
 
+interface SessionFigures {
+	verdict: CostVerdict
+	cost: number | undefined
+	threshold: number
+}
+
 interface Options {
 	over?: number
 	// The target project whose transcripts to read, or absent for this process's own working
@@ -243,6 +246,28 @@ function verdict_of(measurement: OverMeasurement | undefined): CostVerdict {
 	return cost_verdict.classify(measurement, CONTEXT_CUT_THRESHOLD)
 }
 
+// The verdict with the figures it was decided on — the newest request's billed input and the shared
+// threshold — so a report that cites the verdict quotes the same numbers rather than re-measuring.
+// An unmeasurable session has no cost to quote, which is `undefined`, never `0`.
+function figures_of(measurement: OverMeasurement | undefined): SessionFigures {
+	const verdict = verdict_of(measurement)
+	const is_priced = measurement !== undefined && verdict !== UNMEASURABLE_VERDICT
+	const cost = is_priced ? cost_verdict.per_request_cost(measurement) : undefined
+
+	return { verdict, cost, threshold: CONTEXT_CUT_THRESHOLD }
+}
+
+// The `--cut` verdict and its figures as a value, printing nothing. `run:report --handoff` quotes the
+// figures in the hand-off report; `session_verdict` reads the verdict alone.
+function session_figures(
+	cwd: string = process.cwd(),
+	environment: Environment = process.env,
+): SessionFigures {
+	const provider = provider_of(environment)
+
+	return figures_of(provider === undefined ? undefined : measure(cwd, provider, environment))
+}
+
 // The `--cut` verdict as a value, printing nothing. `run:status` bundles
 // this beside the issue state and the carry record, so it needs the token rather than the exit code
 // `run` returns. `unmeasurable` is the read-only counterpart of `report_empty` / the empty-session
@@ -252,10 +277,7 @@ function session_verdict(
 	cwd: string = process.cwd(),
 	environment: Environment = process.env,
 ): CostVerdict {
-	const provider = provider_of(environment)
-	if (provider === undefined) return UNMEASURABLE_VERDICT
-
-	return verdict_of(measure(cwd, provider, environment))
+	return session_figures(cwd, environment).verdict
 }
 
 function run_context(
@@ -294,20 +316,15 @@ function run(
 	return run_over(target, context.over, context.provider, environment)
 }
 
-function main(argv: ReadonlyArray<string>): void {
-	process.exitCode = run(argv)
-}
-
 const cost_cli = {
 	UNMEASURABLE_VERDICT,
 	USAGE,
 	parse_options,
 	to_threshold,
 	run,
+	session_figures,
 	session_verdict,
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) main(process.argv.slice(ARGV_OFFSET))
-
-export type { CostVerdict, Options }
+export type { CostVerdict, Options, SessionFigures }
 export { cost_cli }

package/scripts/cost-runtime/cost-main.ts

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

package/scripts/cost-runtime/cost-transcript.ts

@@ -505,6 +505,7 @@ const cost_transcript = {
 	transcript_directory,
 	transcript_directories,
 	session_cwd,
+	lane_transcript_directories,
 	unit_directory,
 	list_sessions,
 	list_sessions_across,

package/scripts/delegation/delegation-policy.ts

@@ -26,8 +26,9 @@ interface DelegatableStep {
 // Where the pre-implementation reading stops being cheaper in the main line.
 //
 // **A count, not a forecast.** The reads are counted as they are made rather than predicted before
-// the investigation starts, so nothing here rests on guessing how large it will be. Two files the run
-// will not edit stay in the main line, because delegating costs two extra main-line turns — one to
+// the investigation starts, so nothing here rests on guessing how large it will be. It is where the
+// guard refuses, not a budget: a run that knows its subject needs reading delegates before the first
+// read (`run:prep`, #4345). Two stray files the run will not edit are tolerated, because delegating costs two extra main-line turns — one to
 // write the brief, one to read the result, about 18 seconds at roughly 8.8 s of model
 // wait per turn — and below the threshold that round trip costs more than carrying the text.
 const INVESTIGATION_FILE_THRESHOLD = 3
@@ -38,6 +39,15 @@ const INVESTIGATION_FILE_THRESHOLD = 3
 // target, in the main line and sends the continuing sweep to a unit.
 const INVESTIGATION_SEARCH_TURN_THRESHOLD = 3
 
+// `.claude/agents/investigator.md`; a consumer receives it through the plugin as `kit:investigator`.
+const INVESTIGATOR_AGENT = 'investigator'
+
+// The limit and the remedy, worded once: the guard's refusal and `run:prep`'s entry notice both print
+// them, so a run told the step up front is told the same step the refusal would name.
+const INVESTIGATION_LIMIT = `${String(INVESTIGATION_FILE_THRESHOLD)} files read and not edited, or ${String(INVESTIGATION_SEARCH_TURN_THRESHOLD)} search turns, since the last delegated unit`
+// Only the dispatch resets the count, so the step names no `josh delegate` call before it (#4345).
+const INVESTIGATION_STEP = `Dispatch the \`${INVESTIGATOR_AGENT}\` agent (\`kit:${INVESTIGATOR_AGENT}\` in a consumer); it returns \`file:line\` citations, never the file text.`
+
 // The enumeration. Short on purpose: every entry had to name a verifier, and most candidates could
 // not (below).
 const DELEGATABLE_STEPS: ReadonlyArray<DelegatableStep> = [
@@ -59,12 +69,12 @@ const DELEGATABLE_STEPS: ReadonlyArray<DelegatableStep> = [
 	{
 		name: 'followup-filing',
 		// The late-run follow-up filing chain — `issue:file` (which scouts, lints, labels and runs
-		// epic:bundle itself) → epic --add — is a dependency chain `batch:guard`
+		// epic:bundle itself) → epic --add — is a dependency chain the batching guard
 		// correctly keeps one call per step, and what makes it expensive is the ~340k context it runs in
 		// at the tail of a run, not the step count. A fresh unit runs the same
 		// chain at a small context, and the review round cap already composed the finding text, so what
 		// the unit is handed is mechanical: run the commands and act on their deterministic answers. This
-		// is not `batch:guard`'s business — delegation only moves the chain to a cheaper context.
+		// is not the batching guard's business — delegation only moves the chain to a cheaper context.
 		does: 'run the late-run follow-up filing chain in an isolated unit — issue:file (scout, lint, labels, epic:bundle), then epic --add — given the finding text the parent already composed, and return the new Issue number and the epic:bundle answer',
 		verifier:
 			"the parent reads the filed Issue from GitHub with `pnpm josh issue:state <new>`, not the unit's summary; a follow-up reported filed but not created is still absent, the way `epic-child`'s reported-done-but-not-merged child is still open. The finding text came from the parent and `issue:file`'s steps are deterministic, so the unit's work is the mechanical execution `issue:state` confirms",
@@ -181,7 +191,10 @@ function reason_for(name: string): string {
 const delegation_policy = {
 	DELEGATE_VERDICT,
 	INVESTIGATION_FILE_THRESHOLD,
+	INVESTIGATION_LIMIT,
 	INVESTIGATION_SEARCH_TURN_THRESHOLD,
+	INVESTIGATION_STEP,
+	INVESTIGATOR_AGENT,
 	KEEP_VERDICT,
 	DELEGATABLE_STEPS,
 	REJECTED_STEPS,

package/scripts/delegation/duplicate-read-guard.ts

@@ -1,7 +1,4 @@
-#!/usr/bin/env tsx
 import { statSync } from 'node:fs'
-import { text } from 'node:stream/consumers'
-import { fileURLToPath } from 'node:url'
 import { hook_decision } from '#scripts/josh/hook-decision'
 import { lane_guard_policy, type LaneGuardMode } from '#scripts/lane/lane-guard-policy'
 import { json_value } from '#scripts/lib/json-value'
@@ -176,8 +173,8 @@ function is_candidate(call: GuardedCall): boolean {
 }
 
 // A refusable call is refused only where the mode is `refuse`. A lane child is `notice`, so it reaches
-// here and is withheld the refusal — the notice branch carries the guidance instead, because a refusal
-// ends a headless child's turn.
+// here and is withheld the refusal — the notice branch carries the guidance instead, for the reason its
+// `because` in `lane-guard-policy.ts` records.
 function should_block_here(tail: string, call: GuardedCall, refused_at_ms: number): boolean {
 	if (duplicate_mode() !== 'refuse') return false
 
@@ -217,11 +214,6 @@ const duplicate_reads = {
 	NOTICE,
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-	if (process.stdin.isTTY) hook_decision.report_no_payload('duplicate-read:guard')
-	else hook_decision.write_outcome(await text(process.stdin), duplicate_read_outcome)
-}
-
 export {
 	deny_envelope,
 	DISABLED_VALUES,

package/scripts/delegation/investigation-guard.ts

@@ -1,8 +1,6 @@
-#!/usr/bin/env tsx
-import { text } from 'node:stream/consumers'
-import { fileURLToPath } from 'node:url'
+import { agent_session_role } from '#scripts/agent/agent-session-role'
 import { hook_decision, type GuardRun } from '#scripts/josh/hook-decision'
-import { lane_guard_policy, type LaneGuardMode } from '#scripts/lane/lane-guard-policy'
+import { lane_guard_policy } from '#scripts/lane/lane-guard-policy'
 import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
 import { investigation_reads } from './investigation-reads'
 
@@ -21,107 +19,51 @@ import { investigation_reads } from './investigation-reads'
 // file — debugging the guard itself, or a session whose reading really is all edit targets.
 const SWITCH_ENV_KEY = 'JOSH_INVESTIGATION_GUARD'
 
-// This guard's refusal record, and the notice's own record — distinct so a lane-child notice never
-// spends the refusal's stamp, the same split the batching guard keeps.
 const STAMP_PREFIX = 'josh-investigation-guard-'
-const NOTICE_STAMP_PREFIX = 'josh-investigation-guard-notice-'
 
-// **How the guard behaves for the session in hand, decided from the one-place enumeration**.
-// Outside a lane child the mode is `refuse` and the
-// guard refuses; in a dispatched lane child it is `notice`, because a lane child does read unedited
-// files and can dispatch sub-agents, so the reading is there to send out. The enumeration reads `JOSH_LANE_CHILD` against this checkout's own
-// issue only for a guard whose mode it would change, so a person working in a lane sees the guard
-// unchanged. It wraps `investigation_reads.should_block` here rather than inside it so the pure counting
-// rule stays free of process state and its own suite keeps testing it directly.
-function investigation_mode(): LaneGuardMode {
-	return lane_guard_policy.mode_here('investigation')
-}
-
-// A refusable call is refused only where the mode is `refuse` — the main line. A lane child is
-// `notice`, so it reaches the notice branch and is withheld the refusal that would end its headless
-// turn; an `off` some future enumeration sets stays silent here too.
+// **How the guard behaves for the session in hand, decided from the one-place enumeration**. It is
+// `refuse` in a dispatched lane child too (joshuafolkken/kit#3927): a hook denial returns to the model
+// as guidance, and the notice it replaced was measured not to move the reading. It wraps
+// `investigation_reads.should_block` here rather than inside it so the pure counting rule stays free of
+// process state and its own suite keeps testing it directly. A reviewer session stands down: reading
+// the diff's files is its whole task, and it carries the lane's marker, so it would otherwise be refused
+// like the child it reviews — the stand-down `implementation-cut.ts` takes for the same session.
 function should_block(
 	tail: string,
 	call: GuardedCall,
 	refused_at_ms: number,
 	run?: GuardRun,
 ): boolean {
-	if (investigation_mode() !== 'refuse') return false
+	if (
+		agent_session_role.is_reviewer() ||
+		lane_guard_policy.mode_here('investigation') !== 'refuse'
+	) {
+		return false
+	}
 
 	return investigation_reads.should_block(tail, call, refused_at_ms, run)
 }
 
-// The lane-child notice: the same threshold, delivered without a `permissionDecision`. It
-// reads the notify stamp's own record, so a notice never spends the refusal's stamp and re-arms on the
-// next accumulation exactly as the refusal does.
-function should_notify(
-	tail: string,
-	call: GuardedCall,
-	notified_at_ms: number,
-	run?: GuardRun,
-): boolean {
-	if (investigation_mode() !== 'notice') return false
-
-	return investigation_reads.should_block(tail, call, notified_at_ms, run)
-}
-
-// **The lane-child counterpart of REASON, delivered as a notice rather than a refusal**.
-// A dispatched lane child ends its turn on a denial, so
-// the same guidance is carried without a `permissionDecision`: the read proceeds and the child is nudged
-// to delegate rather than killed. It carries no ⛔, so a person watching reads it as advice.
-const NOTICE = `💡 investigation: files read and not edited, or search turns, since the last delegated unit reached the threshold; the read proceeds. Run \`pnpm josh delegate investigation\`, then dispatch the \`${investigation_reads.INVESTIGATOR_AGENT}\` agent (\`kit:${investigation_reads.INVESTIGATOR_AGENT}\` in a consumer); it returns \`file:line\` citations, never the file text. Keep main-line reads to files you will edit.`
-
-// The notice as it reaches the model: the base guidance with the concrete unedited reads named, so a
-// lane child is shown *which* reads to send to a unit rather than only told to delegate. An empty
-// set names nothing and the notice falls back to its guidance alone. The call is part of the notify
-// contract but this guard's wording depends on the tail alone.
-function notice_text(_call: GuardedCall, tail: string): string {
-	const pending = investigation_reads
-		.tally_of(tail)
-		.pending.map((absolute) => investigation_reads.repository_relative(absolute))
-
-	return pending.length === 0
-		? NOTICE
-		: `${NOTICE} Read and not edited so far: ${pending.join(' ')}.`
-}
-
 const GUARD = hook_decision.create_transcript_guard({
 	prefix: STAMP_PREFIX,
 	switch_key: SWITCH_ENV_KEY,
 	is_candidate: investigation_reads.is_refusable_call,
 	should_block,
 	reason: investigation_reads.REASON,
-	// The lane-child notice fires where the refusal is withheld, on a record of its own so it
-	// never spends the refusal's stamp.
-	notify: {
-		prefix: NOTICE_STAMP_PREFIX,
-		should_notify,
-		text: notice_text,
-	},
 })
 
 const investigation_refusal = GUARD.refusal
 const investigation_outcome = GUARD.outcome
 const { is_enabled, refusal_path } = GUARD
-// The notice's stamp path, exposed the way `refusal_path` is so a test can clean it apart from the
-// refusal's record.
-const investigation_notice_path = hook_decision.create_refusal_stamp(NOTICE_STAMP_PREFIX).path
 const { deny_envelope, load_environment_file, DISABLED_VALUES } = hook_decision
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-	if (process.stdin.isTTY) hook_decision.report_no_payload('investigation:guard')
-	else hook_decision.write_outcome(await text(process.stdin), investigation_outcome)
-}
-
 export {
 	deny_envelope,
-	investigation_notice_path,
 	investigation_outcome,
 	investigation_refusal,
 	is_enabled,
 	load_environment_file,
 	refusal_path,
 	DISABLED_VALUES,
-	NOTICE,
 	SWITCH_ENV_KEY,
 }

package/scripts/delegation/investigation-reads.ts

@@ -38,11 +38,10 @@ const SEARCH_LABELS: ReadonlySet<string> = new Set(
 	SEARCH_COMMANDS.map((command) => time_shell.bash_label(command)),
 )
 
-// `.claude/agents/investigator.md`; a consumer receives it through the plugin as `kit:investigator`.
-const INVESTIGATOR_AGENT = 'investigator'
+const { INVESTIGATOR_AGENT } = delegation_policy
 
 // The deny reason is the only text that reaches the model, so it names the count, command and return shape.
-const REASON = `⛔ investigation: ${String(delegation_policy.INVESTIGATION_FILE_THRESHOLD)} files read and not edited, or ${String(delegation_policy.INVESTIGATION_SEARCH_TURN_THRESHOLD)} search turns, since the last delegated unit. Run \`pnpm josh delegate investigation\`, then dispatch the \`${INVESTIGATOR_AGENT}\` agent (\`kit:${INVESTIGATOR_AGENT}\` in a consumer); it returns \`file:line\` citations, never the file text. Keep main-line reads to files you will edit; every read-only search turn counts. \`.claude/skills/workflow-commands/delegation.md\``
+const REASON = `⛔ investigation: ${delegation_policy.INVESTIGATION_LIMIT}. ${delegation_policy.INVESTIGATION_STEP} Keep main-line reads to files you will edit; every read-only search turn counts. \`.claude/skills/workflow-commands/delegation.md\``
 
 interface ReadTally {
 	// The files read and not since edited, resolved.
@@ -61,7 +60,7 @@ interface ReadTally {
 }
 
 // The run's own instructions are not the Issue's subject and cannot be delegated, so they never count.
-// Matched relative to the repository root, so `scripts/eval/prompts/x.ts` stays subject code.
+// Matched relative to the repository root, so `tools/eval/prompts/x.ts` stays subject code.
 const INSTRUCTION_PATHS: ReadonlyArray<string> = ['prompts', '.claude/skills']
 const INSTRUCTION_FILES: ReadonlySet<string> = new Set(['CLAUDE.md', 'AGENTS.md', 'GEMINI.md'])
 const REPOSITORY_ROOT = process.cwd()
@@ -362,7 +361,6 @@ const investigation_reads = {
 	is_session_artifact,
 	is_subject_file,
 	projected_count,
-	repository_relative,
 	resolved,
 	should_block,
 	tally_of,

package/scripts/dependabot/dependabot-cooldown.ts

@@ -0,0 +1,194 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import {
+	DEFAULT_RELEASE_AGE_MINUTES,
+	release_window,
+	type ReleaseWindow,
+} from '#scripts/version/release-window'
+
+// Dependabot's `cooldown` is the workspace's `minimumReleaseAge` restated in days, so a freshly
+// published action or package waits out the same window pnpm and Safe Chain enforce (kit #4023).
+// The edit is line-based and touches only each entry's `cooldown` block: a consumer's own keys and
+// the file's comments survive, which a YAML round trip would discard.
+const DEPENDABOT_FILE = path.join('.github', 'dependabot.yml')
+const MINUTES_PER_DAY = 1440
+// Dependabot accepts `default-days` from 1 to 90.
+const MIN_DAYS = 1
+const MAX_DAYS = 90
+// pnpm's exclusions name npm packages, so only the npm entry receives them.
+const NPM_ECOSYSTEM = 'npm'
+const UPDATES_PATTERN = /^updates:\s*(?:#.*)?$/u
+const ECOSYSTEM_PATTERN = /^\s*(?:-\s+)?package-ecosystem:\s*['"]?([\w-]+)/u
+const TOP_LEVEL_KEY_PATTERN = /^[^\s#-]/u
+const COOLDOWN_KEY = 'cooldown:'
+
+interface UpdateEntry {
+	start: number
+	end: number
+	key_indent: string
+}
+
+function cooldown_days(minutes: number | undefined): number {
+	const days = Math.ceil((minutes ?? DEFAULT_RELEASE_AGE_MINUTES) / MINUTES_PER_DAY)
+
+	return Math.min(MAX_DAYS, Math.max(MIN_DAYS, days))
+}
+
+function quote(value: string): string {
+	return `'${value.replaceAll("'", "''")}'`
+}
+
+function cooldown_lines(ecosystem: string, window: ReleaseWindow, indent: string): Array<string> {
+	const lines = ['cooldown:', `  default-days: ${String(cooldown_days(window.minutes))}`]
+
+	if (ecosystem === NPM_ECOSYSTEM && window.exclusions.length > 0) {
+		lines.push('  exclude:', ...window.exclusions.map((name) => `    - ${quote(name)}`))
+	}
+
+	return lines.map((line) => `${indent}${line}`)
+}
+
+function indent_width(line: string): number {
+	return line.length - line.trimStart().length
+}
+
+function is_blank(line: string | undefined): boolean {
+	return line?.trim() === ''
+}
+
+function trim_trailing_blanks(lines: ReadonlyArray<string>): Array<string> {
+	const trimmed = [...lines]
+	while (trimmed.length > 1 && is_blank(trimmed.at(-1))) trimmed.pop()
+
+	return trimmed
+}
+
+function is_comment(line: string | undefined): boolean {
+	return line?.trimStart().startsWith('#') === true
+}
+
+// A blank line, or a comment left of `width`: it may sit inside a block or head the next one.
+function is_detached(line: string | undefined, width: number): boolean {
+	return is_blank(line) || (is_comment(line) && indent_width(line ?? '') < width)
+}
+
+// The first key line at or after `from` that sits left of `width`, or `limit`.
+function block_stop(
+	lines: ReadonlyArray<string>,
+	from: number,
+	width: number,
+	limit: number,
+): number {
+	const relative = lines
+		.slice(from, limit)
+		.findIndex((line) => !is_blank(line) && !is_comment(line) && indent_width(line) < width)
+
+	return relative === -1 ? limit : from + relative
+}
+
+// The block runs to the next key line left of `width`. A comment left of `width` in the middle stays
+// inside, while the run of such comments right before that key belongs to what follows.
+function block_end(
+	lines: ReadonlyArray<string>,
+	from: number,
+	width: number,
+	limit: number,
+): number {
+	const stop = block_stop(lines, from, width, limit)
+	let end = stop
+
+	for (let index = stop - 1; index >= from && is_detached(lines[index], width); index -= 1) {
+		if (!is_blank(lines[index])) end = index
+	}
+
+	return end
+}
+
+// The next top-level key. A list written flush with `updates:` and a comment at column 0 both still
+// belong to it, so neither ends the list.
+function updates_end(lines: ReadonlyArray<string>, updates: number): number {
+	const relative = lines.slice(updates + 1).findIndex((line) => TOP_LEVEL_KEY_PATTERN.test(line))
+
+	return relative === -1 ? lines.length : updates + 1 + relative
+}
+
+function find_entries(lines: ReadonlyArray<string>, updates: number): Array<UpdateEntry> {
+	const limit = updates_end(lines, updates)
+	const starts = lines
+		.map((line, index) => ({ index, item: /^(\s*-\s+)\S/u.exec(line)?.[1] }))
+		.filter(({ index, item }) => index > updates && index < limit && item !== undefined)
+	const item_width = Math.min(...starts.map(({ item }) => item?.indexOf('-') ?? 0))
+
+	return starts
+		.filter(({ item }) => item?.indexOf('-') === item_width)
+		.map(({ index, item = '' }) => ({
+			start: index,
+			end: block_end(lines, index + 1, item.length, limit),
+			key_indent: ' '.repeat(item.length),
+		}))
+}
+
+// The entry's own `cooldown:` key, either on a key line or on the item line itself (`- cooldown:`).
+function is_cooldown_key(line: string, index: number, key_indent: string): boolean {
+	const is_key_line = index === 0 || line.startsWith(key_indent)
+
+	return is_key_line && line.slice(key_indent.length).startsWith(COOLDOWN_KEY)
+}
+
+// An entry that opened with `- cooldown:` hands its item marker to the next key once the block goes.
+function promote_first_key(rest: ReadonlyArray<string>, marker: string): Array<string> {
+	const first = rest.findIndex((line) => !is_blank(line) && !line.trimStart().startsWith('#'))
+
+	return rest.map((line, index) =>
+		index === first ? `${marker}${line.slice(marker.length)}` : line,
+	)
+}
+
+function without_cooldown(entry: ReadonlyArray<string>, key_indent: string): Array<string> {
+	const start = entry.findIndex((line, index) => is_cooldown_key(line, index, key_indent))
+	if (start === -1) return [...entry]
+	const rest = entry.slice(block_end(entry, start + 1, key_indent.length + 1, entry.length))
+	if (start > 0) return [...entry.slice(0, start), ...rest]
+
+	return promote_first_key(rest, (entry.at(0) ?? '').slice(0, key_indent.length))
+}
+
+function rewrite_entry(
+	entry: ReadonlyArray<string>,
+	key_indent: string,
+	window: ReleaseWindow,
+): Array<string> {
+	const ecosystem = entry.map((line) => ECOSYSTEM_PATTERN.exec(line)?.[1]).find(Boolean)
+	if (ecosystem === undefined) return [...entry]
+	const body = trim_trailing_blanks(without_cooldown(entry, key_indent))
+	const trailing = entry.slice(trim_trailing_blanks(entry).length)
+
+	return [...body, ...cooldown_lines(ecosystem, window, key_indent), ...trailing]
+}
+
+function merge_cooldown(existing: string, window: ReleaseWindow): string {
+	const lines = existing.split('\n')
+	const updates = lines.findIndex((line) => UPDATES_PATTERN.test(line))
+	if (updates === -1) return existing
+
+	for (const { start, end, key_indent } of find_entries(lines, updates).toReversed()) {
+		lines.splice(start, end - start, ...rewrite_entry(lines.slice(start, end), key_indent, window))
+	}
+
+	return lines.join('\n')
+}
+
+function sync_dependabot_cooldown(root: string): boolean {
+	const config_path = path.join(root, DEPENDABOT_FILE)
+	if (!existsSync(config_path)) return false
+	const existing = readFileSync(config_path, 'utf8')
+	const merged = merge_cooldown(existing, release_window.read_release_window(root))
+	if (merged === existing) return false
+	writeFileSync(config_path, merged)
+
+	return true
+}
+
+const dependabot_cooldown = { cooldown_days, merge_cooldown, sync_dependabot_cooldown }
+
+export { dependabot_cooldown }