@joshuafolkken/kit 1.3044.0 → 1.3099.0

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

@@ -0,0 +1,61 @@
+import { z } from 'zod'
+import { issue_auto_ok } from './issue-auto-ok'
+import { AUTO_OK_LABEL, has_label_name } from './issue-labels'
+
+// A body record survives process termination without adding a workflow label or a user prohibition.
+const PREFIX = '<!-- josh:publication '
+const PATTERN = /<!-- josh:publication (?<record>[^\n]*?) -->/u
+const schema = z.object({ labels: z.array(z.string()) })
+
+function is_pending(body: string | undefined): boolean {
+	return body?.includes(PREFIX) === true
+}
+
+function prepare(body: string, labels: ReadonlyArray<string>): string {
+	if (is_pending(body)) throw new Error('Issue already contains a publication record')
+
+	return `${body}\n\n${PREFIX}${JSON.stringify({ labels })} -->\n`
+}
+
+function public_body(body: string): string {
+	return body.replace(PATTERN, '').trimEnd()
+}
+
+function intended_labels(body = ''): ReadonlyArray<string> {
+	const record = PATTERN.exec(body)?.groups?.['record']
+
+	return schema.parse(JSON.parse(record ?? 'null')).labels
+}
+
+function labels_of(
+	body: string | undefined,
+	current: ReadonlyArray<string>,
+): ReadonlyArray<string> {
+	const intended = intended_labels(body)
+	const labels = current.filter((label) => !has_label_name([label], AUTO_OK_LABEL))
+	const decision = issue_auto_ok.decide({
+		is_opted_out: !has_label_name(intended, AUTO_OK_LABEL),
+		is_cross_repository: false,
+		body: public_body(body ?? ''),
+		labels,
+	})
+
+	return decision.is_applied ? [...labels, AUTO_OK_LABEL] : labels
+}
+
+function creation(
+	body: string,
+	labels: ReadonlyArray<string>,
+	is_prepared: boolean,
+): { body: string; labels: ReadonlyArray<string> } {
+	if (!is_prepared) return { body, labels }
+
+	return {
+		body: prepare(body, labels),
+		labels: labels.filter((label) => !has_label_name([label], AUTO_OK_LABEL)),
+	}
+}
+
+const issue_publication_state = { is_pending, prepare, public_body, labels_of, creation }
+
+export { issue_publication_state }

package/scripts/issue/issue-publication.ts

@@ -0,0 +1,144 @@
+import { repo_party } from '#scripts/discovery/repo-party'
+import type { EpicChild, IssueReference } from '#scripts/epic/epic-graph'
+import { epic_live } from '#scripts/epic/epic-live'
+import { epic_parse } from '#scripts/epic/epic-parse'
+import { epic_validate } from '#scripts/epic/epic-validate'
+import { git_gh_api_path } from '#scripts/gh/git-gh-api-path'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { git_gh_exec } from '#scripts/gh/git-gh-exec'
+import { git_gh_issue_memo } from '#scripts/gh/git-gh-issue-memo'
+import { cli_flags } from '#scripts/lib/cli-flags'
+import { error_text } from '#scripts/lib/error-message'
+import { has_label_name, PLANNED_LABEL } from './issue-labels'
+import { issue_number_shape } from './issue-number-shape'
+import { issue_publication_state } from './issue-publication-state'
+import { session_cite } from './session-cite'
+
+interface PreparedChild {
+	child: EpicChild
+	blockers: ReadonlyArray<IssueReference>
+}
+
+async function read_child(number: number, repo: string): Promise<PreparedChild> {
+	return {
+		child: await epic_live.child(number, repo),
+		blockers: await epic_live.blockers(number, repo),
+	}
+}
+
+function has_unrecorded_dependencies(prepared: PreparedChild, epic: EpicChild): boolean {
+	const { child, blockers } = prepared
+	const required = epic_parse
+		.parse_dependency_links(epic.body)
+		.filter((link) => link.blocked === child.number)
+
+	return required.some((link) =>
+		blockers.every((blocker) => blocker.repo !== child.repo || blocker.number !== link.blocker),
+	)
+}
+
+function validate_child(prepared: PreparedChild, epic: EpicChild): void {
+	const { child } = prepared
+	if (!issue_publication_state.is_pending(child.body)) return
+
+	const cited = session_cite.issue(child.number)
+	const is_planned = child.state === 'OPEN' && has_label_name(child.labels, PLANNED_LABEL)
+
+	if (!is_planned) {
+		throw new Error(`Publication withheld: ${cited} needs its recorded plan`)
+	}
+
+	if (has_unrecorded_dependencies(prepared, epic)) {
+		throw new Error(`Publication withheld: ${cited} has unrecorded dependencies`)
+	}
+
+	issue_publication_state.labels_of(child.body, child.labels)
+}
+
+async function publish_child({ child }: PreparedChild): Promise<void> {
+	const body = child.body ?? ''
+	if (!issue_publication_state.is_pending(body)) return
+
+	try {
+		await git_gh_exec.exec_gh_api({
+			path: git_gh_api_path.issue_api_path(String(child.number), child.repo),
+			method: 'PATCH',
+			body: JSON.stringify({
+				body: issue_publication_state.public_body(body),
+				labels: issue_publication_state.labels_of(body, child.labels),
+			}),
+		})
+	} finally {
+		git_gh_issue_memo.forget()
+	}
+}
+
+function require_first_party(repo: string): void {
+	const party = repo_party.classify(repo_party.current_owner(), repo_party.target_owner(repo))
+
+	if (party !== repo_party.FIRST_PARTY) {
+		throw new Error('Publication requires a known first-party tracker')
+	}
+}
+
+// Validate the entire batch before the first atomic body+labels publication. An interrupted batch
+// can be retried: published children are skipped, pending children still require all checks.
+async function publish(epic_number: number, repo: string): Promise<void> {
+	require_first_party(repo)
+	const epic = await epic_live.child(epic_number, repo)
+	const checks = epic_validate.validate_epic({ ...epic, body: epic.body })
+
+	if (!epic_validate.is_epic_valid(checks)) {
+		throw new Error('Publication withheld: epic is incomplete')
+	}
+
+	const children = await Promise.all(
+		epic_parse
+			.parse_task_list_issue_numbers(epic.body)
+			.map(async (number) => await read_child(number, repo)),
+	)
+	for (const child of children) validate_child(child, epic)
+
+	for (const child of children) {
+		// eslint-disable-next-line no-await-in-loop -- each atomic publish can be retried independently
+		await publish_child(child)
+	}
+}
+
+function epic_number_of(argv: ReadonlyArray<string>): string | undefined {
+	const parsed = cli_flags.arguments_of(argv, { publish: { type: 'string' } })
+	if (parsed === undefined || parsed.positionals.length > 0) return undefined
+	const number = parsed.values.publish
+
+	if (number === undefined || !issue_number_shape.ISSUE_NUMBER_PATTERN.test(number)) {
+		return undefined
+	}
+
+	return number
+}
+
+async function publish_here(number: string): Promise<void> {
+	const repo = await git_gh_command.repo_get_name_with_owner()
+	if (repo === undefined) throw new Error('Cannot resolve publication repository')
+	await publish(Number(number), repo)
+	console.info(`Published prepared children of ${session_cite.issue(number)}`)
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const number = epic_number_of(argv)
+	if (number === undefined) return 1
+
+	try {
+		await publish_here(number)
+
+		return 0
+	} catch (error) {
+		console.error(error_text.message_of(error))
+
+		return 1
+	}
+}
+
+const issue_publication = { publish, run }
+
+export { issue_publication }

package/scripts/issue/issue-sample-prime.ts

@@ -6,6 +6,7 @@ import { git_gh_pr_too_large } from '#scripts/gh/git-gh-pr-too-large'
 import { git_closes_keyword } from '#scripts/git/git-closes-keyword'
 import { lane_ledger, type MergeEntry } from '#scripts/lane/lane-ledger'
 import { issue_closing_pr } from './issue-closing-pr'
+import { issue_observation_prime } from './issue-observation-prime'
 import {
 	issue_sample_gate,
 	type Condition,
@@ -105,6 +106,7 @@ async function prime(
 	bodies: ReadonlyArray<string | undefined>,
 	ports: PrimePorts = DEFAULT_PORTS,
 ): Promise<void> {
+	await issue_observation_prime.prime(bodies)
 	const unread = issue_sample_gate.unread_of(bodies)
 
 	if (unread.length === 0) return

package/scripts/issue/issue-search-count.ts

@@ -0,0 +1,26 @@
+import { git_gh_exec } from '#scripts/gh/git-gh-exec'
+import { parse_json } from '#scripts/git/parse-json-array'
+import { z } from 'zod'
+
+const count_schema = z.object({
+	total_count: z.number().int().nonnegative(),
+	incomplete_results: z.literal(false),
+})
+
+// Only for a query that expresses the entire classification in its qualifiers. Body-based
+// classification still needs the listing. Incomplete counts are unread, never a trusted rate.
+async function count(query: string): Promise<number | undefined> {
+	const parameters = new URLSearchParams({ q: query, per_page: '1' })
+
+	try {
+		const raw = await git_gh_exec.exec_gh_api({ path: `search/issues?${parameters.toString()}` })
+
+		return parse_json.parse_json_object_or_undefined(raw, count_schema)?.total_count
+	} catch {
+		return undefined
+	}
+}
+
+const issue_search_count = { count }
+
+export { issue_search_count }

package/scripts/issue/issue-search.ts

@@ -17,6 +17,27 @@ const SEARCH_RESULT_CEILING = 1000
 // is sized for the core REST budget: the search endpoint's own budget is the narrower one, so a
 // search does not spend it in one burst while other `gh` reads hold the remaining slots.
 const PAGE_CONCURRENCY = 4
+const WINDOW_READ_LIMIT = 15
+const MS_PER_SECOND = 1000
+const MS_PER_DAY = 86_400_000
+const SPLIT_DIVISOR = 2
+
+interface SearchWindow {
+	query: string
+	qualifier: string
+	start: number
+	end: number
+	is_open: boolean
+}
+
+type WindowReader = (
+	window: SearchWindow,
+	budget: { remaining: number },
+) => Promise<SearchResult | undefined>
+
+function skips_pages(first: SearchPage, should_split: boolean): boolean {
+	return should_split && first.total_count > SEARCH_RESULT_CEILING
+}
 
 const search_item_schema = z.object({
 	number: z.number().optional(),
@@ -72,10 +93,14 @@ async function read_page(query: string, page: number): Promise<SearchPage | unde
 // Every page of one search. Not `gh api --paginate`: it follows each page's `next` link one page
 // after another, at about 1.5 s a page. The first page names the total, so the rest are fetched
 // together; any page that does not read fails the whole search.
-async function read_pages(query: string): Promise<ReadonlyArray<SearchPage> | undefined> {
+async function read_pages(
+	query: string,
+	should_split = false,
+): Promise<ReadonlyArray<SearchPage> | undefined> {
 	const first = await read_page(query, FIRST_PAGE)
 
 	if (first === undefined) return undefined
+	if (skips_pages(first, should_split)) return [first]
 
 	const rest_numbers = Array.from(
 		{ length: Math.max(page_count(first) - FIRST_PAGE, 0) },
@@ -106,8 +131,80 @@ function to_result(pages: ReadonlyArray<SearchPage>): SearchResult {
 	// handed back — a window past that ceiling is measured on part of itself.
 	const total = pages[0]?.total_count ?? 0
 	const is_incomplete = pages.some((page) => page.incomplete_results)
+	const numbers = issues.map((issue) => issue.number).filter((number) => number > 0)
+	const has_duplicates = new Set(numbers).size !== numbers.length
+
+	return { issues, is_capped: is_incomplete || total !== issues.length || has_duplicates }
+}
+
+function window_query(window: SearchWindow): string {
+	const original_start = Date.parse(window.qualifier.split('>=').at(-1) ?? '')
+
+	if (window.is_open && window.start === original_start) return window.query
+
+	const start = new Date(window.start).toISOString().replace('.000Z', 'Z')
+	const end = new Date(window.end - MS_PER_SECOND).toISOString().replace('.000Z', 'Z')
+	const range = window.is_open ? `>=${start}` : `${start}..${end}`
+
+	return window.query.replace(
+		window.qualifier,
+		() => `${window.qualifier.split(':', 1)[0] ?? ''}:${range}`,
+	)
+}
+
+function merge_windows(results: ReadonlyArray<SearchResult>, total: number): SearchResult {
+	const issues = results.flatMap((result) => result.issues)
+	const unique = new Map(issues.map((issue) => [issue.number, issue]))
+	const is_capped =
+		results.some((result) => result.is_capped) ||
+		unique.size !== total ||
+		unique.size !== issues.length
+
+	return { issues: [...unique.values()], is_capped }
+}
 
-	return { issues, is_capped: is_incomplete || total > issues.length }
+async function split_window(
+	window: SearchWindow,
+	budget: { remaining: number },
+	total: number,
+	read: WindowReader,
+): Promise<SearchResult | undefined> {
+	const middle =
+		Math.floor((window.start + window.end) / SPLIT_DIVISOR / MS_PER_SECOND) * MS_PER_SECOND
+	const left = await read({ ...window, end: middle, is_open: false }, budget)
+
+	if (left === undefined) return undefined
+
+	const right = await read({ ...window, start: middle }, budget)
+
+	return right === undefined ? undefined : merge_windows([left, right], total)
+}
+
+function can_split(first: SearchPage, window: SearchWindow): boolean {
+	return (
+		!first.incomplete_results &&
+		first.total_count > SEARCH_RESULT_CEILING &&
+		window.end - window.start > MS_PER_SECOND
+	)
+}
+
+async function read_window(
+	window: SearchWindow,
+	budget: { remaining: number },
+): Promise<SearchResult | undefined> {
+	if (budget.remaining === 0) return { issues: [], is_capped: true }
+
+	budget.remaining -= 1
+	const pages = await read_pages(window_query(window), true)
+
+	if (pages === undefined) return undefined
+
+	const result = to_result(pages)
+	const [first] = pages
+
+	if (first === undefined || !can_split(first, window)) return result
+
+	return await split_window(window, budget, first.total_count, read_window)
 }
 
 // The search's issues, or `undefined` when any page could not be read.
@@ -121,7 +218,35 @@ async function search(query: string): Promise<SearchResult | undefined> {
 	}
 }
 
-const issue_search = { search, search_path }
+// The final interval stays open: the partition's union is the original lower-bounded query,
+// including timestamps ahead of this process. Never retry an incomplete or failed response.
+function rate_qualifier(query: string): string | undefined {
+	return /\b(?:created|closed):>=\d{4}-\d{2}-\d{2}\b/u.exec(query)?.[0]
+}
+
+async function search_complete(
+	query: string,
+	now_ms: number = Date.now(),
+): Promise<SearchResult | undefined> {
+	const qualifier = rate_qualifier(query)
+
+	if (qualifier === undefined) return await search(query)
+
+	const start = Date.parse(qualifier.split('>=').at(-1) ?? '')
+	const now = (Math.floor(now_ms / MS_PER_DAY) + 1) * MS_PER_DAY
+	const end = Math.max(now, start + MS_PER_SECOND)
+
+	try {
+		return await read_window(
+			{ query, qualifier, start, end, is_open: true },
+			{ remaining: WINDOW_READ_LIMIT },
+		)
+	} catch {
+		return undefined
+	}
+}
+
+const issue_search = { search, search_complete, search_path }
 
 export type { SearchIssue, SearchResult }
 export { issue_search }

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

@@ -220,6 +220,10 @@ async function placed(issue: SpillIssue, follow_up: number): Promise<number> {
 async function place(issue: SpillIssue, follow_up: number): Promise<number> {
 	const exit_code = await placed(issue, follow_up)
 
+	console.info(
+		`Prepared ${session_cite.issue(follow_up)} stays unpublished: record its plan with issue:plan --planned --no-notify, then run pnpm josh issue:file --publish <E> after placement succeeds.`,
+	)
+
 	if (exit_code !== SUCCESS_EXIT_CODE) {
 		console.error(
 			`✖ ${session_cite.issue(follow_up)} was not placed — place it with \`pnpm josh epic --add <E> ${String(follow_up)} --after ${String(issue.issue_number)}\`.`,

package/scripts/issue/upstream-interrupt-cli.ts

@@ -41,7 +41,7 @@ const RECOMMENDED = 'Wait for the upstream fix'
 const NOTIFY_COMMAND = 'pnpm josh notify --task-type confirmation'
 const ALTERNATIVES = ['Defer the upstream issue and resume the finder now']
 
-interface Interrupt {
+interface ParsedInterrupt {
 	finder: string
 	title: string
 	repo: string
@@ -49,6 +49,10 @@ interface Interrupt {
 	is_blocking_finder: boolean
 }
 
+interface Interrupt extends ParsedInterrupt {
+	finder_repo: string
+}
+
 interface Positionals {
 	finder: string
 	title: string
@@ -64,7 +68,7 @@ function positionals_of(positionals: ReadonlyArray<string>): Positionals | undef
 	return is_shaped ? { finder, title } : undefined
 }
 
-function parse(argv: ReadonlyArray<string>): Interrupt | undefined {
+function parse(argv: ReadonlyArray<string>): ParsedInterrupt | undefined {
 	const parsed = cli_flags.arguments_of(argv, OPTIONS)
 
 	if (parsed === undefined) return undefined
@@ -197,11 +201,13 @@ async function kept_body(interrupt: Interrupt): Promise<Interrupt | undefined> {
 
 async function comment(interrupt: Interrupt, body: string): Promise<boolean> {
 	try {
-		console.info(`comment: ${await git_gh_command.issue_comment(interrupt.finder, body)}`)
+		const url = await git_gh_command.issue_comment(interrupt.finder, body, interrupt.finder_repo)
+
+		console.info(`comment: ${url}`)
 
 		return true
 	} catch (error) {
-		const rerun = `pnpm josh issue:comment ${interrupt.finder} --body-file ${await saved(body)}`
+		const rerun = `GH_REPO=${shell_quote.word(interrupt.finder_repo)} pnpm josh issue:comment ${interrupt.finder} --body-file ${await saved(body)}`
 
 		return stopped('comment', error_text.message_of(error), rerun)
 	}
@@ -272,7 +278,17 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 		return FAILURE_EXIT_CODE
 	}
 
-	return (await interrupt_by_party(interrupt)) ? SUCCESS_EXIT_CODE : FAILURE_EXIT_CODE
+	const finder_repo = await git_gh_command.repo_get_name_with_owner()
+
+	if (finder_repo === undefined) {
+		console.error('✖ upstream:interrupt stopped: the finder repository could not be resolved.')
+
+		return FAILURE_EXIT_CODE
+	}
+
+	return (await interrupt_by_party({ ...interrupt, finder_repo }))
+		? SUCCESS_EXIT_CODE
+		: FAILURE_EXIT_CODE
 }
 
 const upstream_interrupt_cli = { run }

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

@@ -512,7 +512,7 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 	'lane:stats': {
 		...MEASURE_ARGUMENTS,
 		description:
-			'Print period lane throughput, stage, stop (by failed CI check, longest first), check and machine-load statistics; --sinks shows stage totals, --over lane chains, --why cause groups above a net-minute threshold, and --pairs scoped pair runs',
+			'Print period lane throughput, stage, stop (by failed CI check, longest first), check, runnable-to-dispatch wait and machine-load statistics; --sinks shows stage totals, --over lane chains, --why cause groups above a net-minute threshold, and --pairs scoped pair runs',
 		category: 'AI tools',
 		reference: [
 			'(--period <days> | --since <instant>) [--limit <lane-limit> | --sinks [<minutes>] | --over <minutes> | --why <minutes> | --pairs]',

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

@@ -65,7 +65,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 	'lint:related': {
 		script: 'scripts/lint/lint-related.ts',
 		description:
-			'Check only the changed files with prettier and eslint, and in kit the source guard tests (whole tree on fallback)',
+			'Apply eslint fixes and prettier to the resolved scope, then check remaining errors and in kit the source guard tests (whole tree on fallback)',
 		category: 'Development',
 		reference: [FILE_ARGUMENTS, 'developer', ['processes']],
 		core_weight: core_weights.CORE_WEIGHTS.lint,

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

@@ -293,6 +293,15 @@ const ISSUE_WRITE_COMMANDS: Record<string, CommandEntry> = {
 					names: ['--no-auto-ok'],
 					description: 'needs human judgement or a verified user prohibition; no `auto-ok`.',
 				},
+				{
+					names: ['--prepare'],
+					description: 'create an unpublished child; `--route split` implies this.',
+				},
+				{
+					names: ['--publish <E>'],
+					description:
+						"validate/publish epic E's prepared children; retry the same epic on failure.",
+				},
 				{
 					names: ['--release'],
 					description:

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

@@ -22,7 +22,7 @@ const RUN_COMMANDS: Record<string, CommandEntry> = {
 		// A `--halfrun-stop` / `--human-review-stop` / `--prrun-stop` sends the stop confirmation.
 		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
 		reference: [
-			'[<issue> [--fullrun | --halfrun-stop | --human-review-stop | --prrun-stop]] | --adopt <issue>',
+			'[<issue> [--fullrun | --halfrun-stop | --halfrun-round | --human-review-stop | --prrun-stop]] | --adopt <issue>',
 			'automation',
 			['files'],
 		],
@@ -44,6 +44,11 @@ const RUN_COMMANDS: Record<string, CommandEntry> = {
 					description:
 						'marks a `halfrun` stop for `run:entry` to adopt, and sends its `confirmation` Telegram; answers `e2e-owed` (exit 1) until `test:e2e` answered green on this tree.',
 				},
+				{
+					names: ['--halfrun-round'],
+					description:
+						"starts a `halfrun` fix round: re-opens the issue's stopped `halfrun` record as running, owned by this session; answers `busy` (exit 1) when the tree holds no such stop.",
+				},
 				{
 					names: ['--human-review-stop'],
 					description:

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

@@ -58,7 +58,7 @@ const SHIP_COMMANDS: Record<string, CommandEntry> = {
 			'Start test:pinned in the background, run the gate and, once it is green, write the /code-review brief to a file, printing its path (--join to join them; it stops on an unpinned change)',
 		category: 'AI tools',
 		reference: [
-			'[--code-only] [--unpinned-ok "<reason>"] | --join [--fixing] | --pinned | --push',
+			'[--code-only] [--unpinned-ok "<reason>"] | --join [--fixing] | --pinned | --push [<slots>]',
 			'automation',
 			['processes', 'files', 'git', 'network'],
 		],
@@ -86,11 +86,11 @@ const SHIP_COMMANDS: Record<string, CommandEntry> = {
 				},
 				{
 					arguments: '--pinned',
-					note: "read test:pinned alone (the ship's pre-detach reads it anyway); a lane child returns at once",
+					note: "collect a stopped ship's remaining verdicts before editing or retrying; a lane child waits only for this continuation",
 				},
 				{
-					arguments: '--push',
-					note: 'launched by a lane open: push and open the PR at a green gate',
+					arguments: '--push 2',
+					note: 'launched by a lane open: push and open the PR at a green gate, recording the review plan’s slot count on the ledger',
 				},
 			],
 		},
@@ -191,7 +191,7 @@ const SHIP_COMMANDS: Record<string, CommandEntry> = {
 				{
 					names: ['--review'],
 					description:
-						'runs round 1 beside the gate; after sync and round 1, an owed round 2 runs beside the gate and joins before the PR opens. A High or unfixed Medium stops the ship. A pre-detach `test:pinned` stop probes remaining hunks in the background for the next pre-detach.',
+						'runs round 1 beside the gate; after sync and round 1, an owed round 2 runs beside the gate and joins before the PR opens. A High or unfixed Medium stops the ship. After a pre-detach `test:pinned` stop, collect remaining verdicts with `pnpm josh run:review --pinned` before editing or retrying.',
 				},
 				{
 					names: ['--unpinned-ok <reason>'],

package/scripts/josh/josh-run.ts

@@ -1,3 +1,4 @@
+import { run_startup } from '#scripts/run/startup/run-startup'
 import { execa } from 'execa'
 
 // One captured `pnpm josh` subprocess. A composite command that collapses a
@@ -42,9 +43,11 @@ function extra_options(
 	timeout_ms: number | undefined,
 	environment: Readonly<Record<string, string>> | undefined,
 ): ExtraOptions {
+	const child_environment = { ...run_startup.environment(), ...environment }
+
 	return {
 		...(timeout_ms !== undefined && { timeout: timeout_ms }),
-		...(environment !== undefined && { env: environment }),
+		...(Object.keys(child_environment).length > 0 && { env: child_environment }),
 	}
 }
 
@@ -76,7 +79,7 @@ async function josh_run(
 }
 
 async function josh_run_at(args: ReadonlyArray<string>, cwd: string): Promise<JoshResult> {
-	return await run_with_options(args, false, { cwd })
+	return await run_with_options(args, false, { ...extra_options(undefined, undefined), cwd })
 }
 
 // A step whose failure ends the composite: its stderr, else its stdout, else the exit code is the

package/scripts/josh/shared-cache.ts

@@ -1,6 +1,7 @@
 import { git_common_directory } from '#scripts/git/git-common-directory'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
 import { json_value } from '#scripts/lib/json-value'
+import { run_startup } from '#scripts/run/startup/run-startup'
 import { z } from 'zod'
 import { stamp_file } from './stamp-file'
 
@@ -49,6 +50,12 @@ function read<T>(
 ): T | undefined {
 	const parsed = schema.safeParse(read_value(slot, key, now_ms))
 
+	run_startup.metric(
+		'cache',
+		parsed.success && parsed.data !== undefined ? 'hit' : 'miss',
+		`${slot.prefix}:${key}`,
+	)
+
 	return parsed.success ? parsed.data : undefined
 }
 
@@ -73,7 +80,15 @@ async function remember<T>(
 
 	if (cached !== undefined) return cached
 
-	const value = await compute()
+	const value = await run_startup.phase(
+		`cache fill ${request.slot.prefix}`,
+		async () => {
+			run_startup.metric('cache', 'fill', `${request.slot.prefix}:${request.key}`)
+
+			return await compute()
+		},
+		{ edge_of: (result) => (result === undefined ? 'failed' : 'done') },
+	)
 
 	if (value !== undefined) write(request.slot, request.key, value, now_ms)