@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/rules/repo-admin.ts

@@ -0,0 +1,132 @@
+import { bash_triggers } from './bash-triggers'
+import { direct_pr_create } from './direct-pr-create'
+import { gh_api } from './gh-api'
+import { git_argv } from './git-argv'
+import { pr_merge } from './pr-merge'
+import { shell_segments } from './shell-segments'
+
+// The trigger and the delivered text behind the `repo-admin` row of `delivered-rules.ts`: a write to
+// the repository's own administration — the rulesets and branch protection, the collaborators and
+// their invitations, the secrets and variables, the webhooks and deploy keys, and the repository's
+// settings. The server-side ruleset is one of the two real boundaries of an unattended run, and the
+// trust gate reads write permission, so one injected call that adds a collaborator or disables the
+// ruleset hands the backlog to an attacker (joshuafolkken/kit#4650).
+//
+// **A `DELETE` is `destructive-command`'s**, which refuses every `DELETE repos/…` already; this row
+// takes the other write methods, so one row claims each call. `gh ruleset` has no write subcommand.
+//
+// **It fires on every occurrence**, for the reason `git-force.ts` does.
+
+const GH_COMMAND = 'gh'
+const DELETE_METHOD = 'DELETE'
+const PATCH_METHOD = 'PATCH'
+
+// `repos/<o>/<r>` as a path or a full URL (`https://api.github.com/repos/…`), anchored on the whole
+// argument so a path smuggled into a field value (`-f x=repos/…/hooks`) is not read as the endpoint.
+const REPOSITORY_PREFIX = String.raw`^['"]?(?:https?:\/\/[^/\s'"]+)?\/?repos\/[^/\s'"]+\/[^/\s'"]+`
+// The administration endpoints under it — the environments whole, since their protection rules move
+// the deployment boundary as their secrets do.
+const ADMIN_PATH = new RegExp(
+	REPOSITORY_PREFIX +
+		String.raw`\/(?:rulesets|branches\/[^\s'"]+\/protection|collaborators|invitations|hooks|keys|` +
+		String.raw`transfer|actions\/permissions|environments|` +
+		String.raw`(?:actions|dependabot|codespaces)\/(?:secrets|variables))(?:[/?'"]|$)`,
+	'u',
+)
+// The repository itself — a `PATCH` here edits its settings (visibility, default branch, merge rules).
+const REPOSITORY_BODY = new RegExp(String.raw`${REPOSITORY_PREFIX}\/?['"]?$`, 'u')
+// The GraphQL mutations that do what the endpoints above do. Looked for in the whole line, as
+// `pr-merge.ts` does, since the segment cut ignores quotes; a body read from a file is `pr-merge`'s.
+const ADMIN_MUTATIONS =
+	/\b(?:updateRepository|archiveRepository|(?:create|update|delete)(?:BranchProtectionRule|RepositoryRuleset|Environment))\b/u
+
+function is_admin_target(argument: string, method: string | undefined): boolean {
+	return ADMIN_PATH.test(argument) || (method === PATCH_METHOD && REPOSITORY_BODY.test(argument))
+}
+
+function is_admin_graphql_call(command: string, args: ReadonlyArray<string>): boolean {
+	return pr_merge.is_graphql_call(GH_COMMAND, args) && ADMIN_MUTATIONS.test(command)
+}
+
+// Judged on the call with its wrapper cut off, as `destructive-command.ts` does.
+function is_admin_api_call(command: string, args: ReadonlyArray<string>): boolean {
+	const call = [GH_COMMAND, ...args].join(' ')
+
+	if (!gh_api.is_gh_api(call) || !gh_api.is_write(call)) return false
+	if (is_admin_graphql_call(command, args)) return true
+
+	const method = gh_api.method_of(call)
+
+	if (method === DELETE_METHOD) return false
+
+	return args.some((argument) => is_admin_target(argument, method))
+}
+
+// The read subcommands of the groups whose every other subcommand writes.
+const READ_ACTIONS: ReadonlySet<string> = new Set(['list', 'ls', 'get', 'view'])
+const ACTION_POSITION = 1
+const SUB_ACTION_POSITION = 2
+// Where the word that decides read vs write sits, keyed by the group (`gh secret <verb>`) or by the
+// group and action (`gh repo deploy-key <verb>`); `gh repo edit` is its own verb and only writes.
+const VERB_POSITIONS: ReadonlyMap<string, number> = new Map([
+	['secret', ACTION_POSITION],
+	['variable', ACTION_POSITION],
+	['repo edit', ACTION_POSITION],
+	['repo deploy-key', SUB_ACTION_POSITION],
+])
+
+// The verb of an administration subcommand, or `undefined` for every other call. Read off the
+// positional words, so a repository selector before the group (`gh -R o/r secret set`) is skipped.
+function admin_verb(args: ReadonlyArray<string>): string | undefined {
+	const words = direct_pr_create.positional_words(args, direct_pr_create.API_VALUE_TAKING_FLAGS)
+	const position =
+		VERB_POSITIONS.get(words[0] ?? '') ??
+		VERB_POSITIONS.get(words.slice(0, SUB_ACTION_POSITION).join(' '))
+
+	if (position === undefined) return undefined
+
+	return words[position] ?? ''
+}
+
+function is_admin_cli_call(args: ReadonlyArray<string>): boolean {
+	const verb = admin_verb(args)
+
+	return verb !== undefined && !READ_ACTIONS.has(verb)
+}
+
+function is_admin_segment(command: string, segment: string): boolean {
+	const args = git_argv.arguments_of(segment, GH_COMMAND)
+
+	if (args === undefined) return false
+
+	return is_admin_cli_call(args) || is_admin_api_call(command, args)
+}
+
+function is_repo_admin_write(command: string): boolean {
+	return shell_segments.commands_of(command).some((segment) => is_admin_segment(command, segment))
+}
+
+const REPO_ADMIN_REASON =
+	'⛔ repository administration: a write to the rulesets, branch protection, collaborators, ' +
+	'invitations, secrets, variables, webhooks, deploy keys or repository settings moves the ' +
+	'boundary an unattended run relies on, which is Tier C. Ask the user to run it. It fires on every occurrence ' +
+	'(`prompts/collaboration-workflow/operating-rules.md`).'
+
+const ROW = {
+	id: 'repo-admin',
+	is_trigger: bash_triggers.on_bash_command(is_repo_admin_write),
+	reason: REPO_ADMIN_REASON,
+	decide: (): boolean => true,
+	about: {
+		title: 'Repository administration',
+		topic: '`operating-rules.md`',
+		fires:
+			'a `gh api` POST / PUT / PATCH (path or URL) to the rulesets, branch protection, collaborators, invitations, secrets, variables, hooks, keys, environments, actions permissions or transfer, a `PATCH` of the repository, the matching GraphQL mutations, `gh secret` / `gh variable` writes, `gh repo edit` / `deploy-key` writes. Every occurrence',
+		quiet:
+			'`gh secret list`, `gh variable get`, a `gh api` read — a `DELETE` is `destructive-command`',
+	},
+}
+
+const repo_admin = { REPO_ADMIN_REASON, ROW, is_repo_admin_write }
+
+export { repo_admin }

package/scripts/rules/reviewer-foreground.ts

@@ -0,0 +1,88 @@
+import { lane_child_marker } from '#scripts/lane/lane-child-marker'
+import { json_value } from '#scripts/lib/json-value'
+import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
+import { agent_model } from './agent-model'
+
+// A lane child's `reviewer` dispatched without `run_in_background: false` is run in the foreground
+// instead (joshuafolkken/kit#5154).
+//
+// **A headless child's turn end kills a background reviewer**, so `chain-rule.md` → "A lane child" says
+// not to background it. The subagent tool launches in the background by default, and 23 of 178 lanes
+// did: #5129 polled the output file in a `sleep` loop, then waited again on `run:review --join`.
+//
+// **The fix is the same call with one field, so the hook makes it** (`guard-remedy.ts`): no round trip,
+// and a build whose tool declares no `run_in_background` drops the added field as it drops the typed
+// one. Lane children only — an interactive turn is re-invoked by the background result.
+
+// `kit:reviewer` is the consumer's spelling of the same definitions.
+const REVIEWER_AGENTS: ReadonlySet<string> = new Set(['reviewer', 'reviewer-verification'])
+
+const BACKGROUND_FIELD = 'run_in_background'
+
+const CHAIN_RULE_STEP = '`.claude/skills/workflow-commands/chain-rule.md` → "A lane child"'
+
+const KILLED = 'reviewer foreground: a lane child’s turn end kills a background `reviewer`'
+const FOREGROUND = `\`${BACKGROUND_FIELD}: false\``
+
+const REVIEWER_FOREGROUND_NOTE = `↻ ${KILLED}, so the call ran with ${FOREGROUND} (${CHAIN_RULE_STEP}).`
+
+// Delivered only where the rewrite cannot reach the call.
+const REVIEWER_FOREGROUND_REASON = `⛔ ${KILLED}. Reissue the call with ${FOREGROUND} (${CHAIN_RULE_STEP}). It fires on every occurrence.`
+
+function is_reviewer(call: GuardedCall): boolean {
+	if (!agent_model.SUBAGENT_TOOLS.has(call.name) || !json_value.is_record(call.input)) return false
+
+	const type = call.input['subagent_type']
+
+	return typeof type === 'string' && REVIEWER_AGENTS.has(type.split(':').at(-1) ?? '')
+}
+
+function is_foreground(call: GuardedCall): boolean {
+	return json_value.is_record(call.input) && call.input[BACKGROUND_FIELD] === false
+}
+
+function is_background_reviewer(
+	call: GuardedCall,
+	is_lane_child: boolean = lane_child_marker.is_child_of(process.cwd()),
+): boolean {
+	return is_lane_child && is_reviewer(call) && !is_foreground(call)
+}
+
+function foreground_input(
+	call: GuardedCall,
+	is_lane_child: boolean = lane_child_marker.is_child_of(process.cwd()),
+): Record<string, unknown> | undefined {
+	if (!is_background_reviewer(call, is_lane_child) || !json_value.is_record(call.input)) {
+		return undefined
+	}
+
+	return { ...call.input, [BACKGROUND_FIELD]: false }
+}
+
+const ROW = {
+	id: 'reviewer-foreground',
+	is_trigger: (call: GuardedCall): boolean => is_background_reviewer(call),
+	reason: REVIEWER_FOREGROUND_REASON,
+	decide: (): boolean => true,
+	keeps: (call: GuardedCall): boolean => is_reviewer(call) && is_foreground(call),
+	reaches: is_reviewer,
+	rewrite: (call: GuardedCall): Record<string, unknown> | undefined => foreground_input(call),
+	rewrite_note: REVIEWER_FOREGROUND_NOTE,
+	about: {
+		title: 'Lane child reviewer dispatched in the foreground',
+		topic: CHAIN_RULE_STEP,
+		fires:
+			'a dispatched lane child’s `Agent` / `Task` call of the `reviewer` or `reviewer-verification` type without `run_in_background: false` — rewritten with it, every occurrence',
+		quiet: 'not a lane child, another agent type, or `run_in_background: false` set',
+	},
+}
+
+const reviewer_foreground = {
+	REVIEWER_FOREGROUND_NOTE,
+	REVIEWER_FOREGROUND_REASON,
+	ROW,
+	foreground_input,
+	is_background_reviewer,
+}
+
+export { reviewer_foreground }

package/scripts/rules/round-one-check-related.ts

@@ -0,0 +1,120 @@
+import type { GuardRun } from '#scripts/josh/hook-decision'
+import { lane_child_marker } from '#scripts/lane/lane-child-marker'
+import { time_density_hook } from '#scripts/time-runtime/time-density-hook'
+import { time_markers } from '#scripts/time-runtime/time-markers'
+import { time_shell } from '#scripts/time-runtime/time-shell'
+import { time_transcript_line, type Block } from '#scripts/time-runtime/time-transcript-line'
+import { bash_triggers } from './bash-triggers'
+import { shell_segments } from './shell-segments'
+import { tail_commands } from './tail-commands'
+
+// A lane child is stopped from running `check:related` on round 1's fixes before it joins the review.
+//
+// **Ship reruns the scoped pair on the fixed tree.** `chain-rule.md` → "A lane child" says the round's
+// fixes take no `check:related` unless a brief follows: `josh ship`'s pre-detach checks the tree the
+// fixes left. The #5168 lane fixed two findings between its brief and `run:review --join` and ran
+// `check:related` after each, 12 of its 70 minutes, because the sentence was prose with no delivery.
+//
+// **The material is the run's own calls, read in order off the transcript tail.** The brief is a
+// `run:review` in its writing mode, the fix an `Edit` / `Write` after it, and the round closes at
+// `run:review --join` or `ship --detach`. Neither the brief file nor the join leaves a record on disk
+// that tells "briefed, not yet joined" apart, so the tail is the one source that can answer.
+
+// Named canonically — `shell_segments.is_josh_command` expands an alias (`josh cr`) before the match.
+const CHECK_COMMANDS: ReadonlySet<string> = new Set(['check:related'])
+const REVIEW_COMMANDS: ReadonlySet<string> = new Set(['run:review'])
+const SHIP_COMMANDS: ReadonlySet<string> = new Set(['ship'])
+const JOIN_FLAG = /(?:^|\s)--join(?:[=\s]|$)/u
+// The `run:review` modes that read a running check rather than write a brief.
+const READING_MODE_FLAG = /(?:^|\s)--(?:pinned|push)(?:[=\s]|$)/u
+const DETACH_FLAG = /(?:^|\s)--detach(?:[=\s]|$)/u
+
+type RoundEvent = 'brief' | 'close' | 'edit' | 'none'
+
+function review_event(segment: string): RoundEvent {
+	if (JOIN_FLAG.test(segment)) return 'close'
+
+	return READING_MODE_FLAG.test(segment) ? 'none' : 'brief'
+}
+
+function segment_event(segment: string): RoundEvent {
+	if (shell_segments.is_josh_command(segment, REVIEW_COMMANDS)) return review_event(segment)
+
+	const is_detach =
+		shell_segments.is_josh_command(segment, SHIP_COMMANDS) && DETACH_FLAG.test(segment)
+
+	return is_detach ? 'close' : 'none'
+}
+
+function block_events(block: Block): ReadonlyArray<RoundEvent> {
+	if (tail_commands.is_bash_use(block)) {
+		const segments = shell_segments.segments_of(time_shell.bash_command(block.input))
+
+		return segments.map((segment) => segment_event(segment))
+	}
+
+	const is_edit = time_markers.tool_marker(block.name, block.input) === time_markers.EDIT_MARKER
+
+	return is_edit ? ['edit'] : []
+}
+
+// Whether the tail's last brief was followed by a fix and by neither a join nor a detach.
+function fixes_an_open_round(tail: string): boolean {
+	const blocks = time_transcript_line.parse_text(tail).flatMap((line) => line.blocks)
+	const events = blocks.flatMap((block) => block_events(block))
+	const brief_at = events.lastIndexOf('brief')
+
+	if (brief_at === -1) return false
+
+	const since_brief = new Set(events.slice(brief_at))
+
+	return since_brief.has('edit') && !since_brief.has('close')
+}
+
+function runs_check_related(command: string): boolean {
+	return shell_segments
+		.segments_of(command)
+		.some((segment) => shell_segments.is_josh_command(segment, CHECK_COMMANDS))
+}
+
+// **The command test comes first and the world is consulted second**: a person working in a lane
+// carries no mark and sees no refusal.
+function is_candidate(command: string): boolean {
+	if (!runs_check_related(command)) return false
+
+	return lane_child_marker.is_child_of(process.cwd())
+}
+
+// Refused on every occurrence while the round stays open: the way on is the join, never a reissue.
+function decide(_call: unknown, run: GuardRun): boolean {
+	return fixes_an_open_round(time_density_hook.read_tail(run.transcript))
+}
+
+const ROUND_ONE_CHECK_RELATED_REASON =
+	"⛔ round-one check:related: round 1's fixes need no `check:related` — ship's pre-detach reruns the " +
+	'scoped pair on the fixed tree; refused on every occurrence. Go on to `pnpm josh run:review --join`; ' +
+	'`--join --fixing` while round 1 has fixes to make (`.claude/skills/workflow-commands/chain-rule.md` → "A lane child").'
+
+// It declares no `keeps`: skipping the check is the absence of a call, so the row is reported
+// unmeasured rather than scored on an act that does not exist (`lane-split-park.ts`).
+const ROW = {
+	id: 'round-one-check-related',
+	is_trigger: bash_triggers.on_bash_command(is_candidate),
+	reason: ROUND_ONE_CHECK_RELATED_REASON,
+	decide,
+	about: {
+		title: "No check:related on round 1's fixes",
+		topic: '`.claude/skills/workflow-commands/chain-rule.md` → "A lane child"',
+		fires:
+			"`pnpm josh check:related` (`josh cr`) in a lane child after an `Edit` / `Write` that follows `run:review`'s brief, before `run:review --join` or `ship --detach`. Every occurrence",
+		quiet: 'no fix since the brief, already joined or detached, or not a lane child',
+	},
+}
+
+const round_one_check_related = {
+	ROUND_ONE_CHECK_RELATED_REASON,
+	ROW,
+	fixes_an_open_round,
+}
+
+export { round_one_check_related }

package/scripts/rules/rule-body-guard.ts

@@ -2,6 +2,7 @@ import { json_value } from '#scripts/lib/json-value'
 import { file_reader } from '#scripts/lib/read-file'
 import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
 import { bash_triggers } from './bash-triggers'
+import { edit_tool } from './edit-tool'
 import { shell_segments } from './shell-segments'
 import { tail_commands } from './tail-commands'
 
@@ -29,10 +30,9 @@ import { tail_commands } from './tail-commands'
 // refuses until it is met. It passes on answering the questions, not on reading the
 // reminder. Keeping the rule is therefore running those two commands, which `keeps` names.
 
-// The two edit tools the `PreToolUse` matcher routes here. A `Write` carries the whole new file; an
-// `Edit` carries the region as `old_string` / `new_string`.
-const EDIT_TOOL = 'Edit'
-const WRITE_TOOL = 'Write'
+// The two edit tools the `PreToolUse` matcher routes here (`edit-tool.ts`). A `Write` carries the whole
+// new file; an `Edit` carries the region as `old_string` / `new_string`.
+const { WRITE, is_edit_tool, string_field } = edit_tool
 
 // The three rule-document families question 0 must be pushed at: the resident source, the
 // collaboration-workflow prompts, and the skill bodies. Anchored at a path separator or the string
@@ -69,12 +69,6 @@ function adds_rule_prose(old_text: string, new_text: string): boolean {
 	return prose_of(new_text).length - prose_of(old_text).length >= MIN_APPENDED_PROSE
 }
 
-function string_field(input: Record<string, unknown>, key: string): string {
-	const value = input[key]
-
-	return typeof value === 'string' ? value : ''
-}
-
 // The file's current text, read synchronously before the write lands so a `Write` has an `old` to
 // measure against. Injected so the suite controls it without touching the real filesystem, the way
 // `file-body.ts` injects its existence check. A new file reads as empty, so its whole body is added.
@@ -87,7 +81,7 @@ function texts_of(
 	input: Record<string, unknown>,
 	read: (file_path: string) => string,
 ): { old_text: string; new_text: string } {
-	if (name === WRITE_TOOL) {
+	if (name === WRITE) {
 		return {
 			old_text: read(string_field(input, 'file_path')),
 			new_text: string_field(input, 'content'),
@@ -100,10 +94,6 @@ function texts_of(
 	}
 }
 
-function is_edit_tool(name: string): boolean {
-	return name === EDIT_TOOL || name === WRITE_TOOL
-}
-
 // The call's input when it is an edit of a rule document, and `undefined` otherwise. The tool-name and
 // path tests run before the text read, so an ordinary edit pays nothing and a `Write`'s file read
 // happens only for a rule document.
@@ -178,6 +168,14 @@ const ROW = {
 	reason: RULE_BODY_REASON,
 	already_satisfied: answered_placement,
 	keeps: bash_triggers.on_bash_command(runs_placement_oracle),
+	about: {
+		title: 'Question 0 and the ordering question before writing a rule into prose',
+		topic: '`residency.md`',
+		fires:
+			'an `Edit` / `Write` to `CLAUDE.md` / `prompts/**/*.md` / `.claude/skills/**/*.md` appending at least the threshold. Refused until both `pnpm josh oracle:list` and `pnpm josh run:step` ran',
+		quiet:
+			'not a rule document, an append under the threshold (typo, link swap, deletion), or both commands ran',
+	},
 }
 
 const rule_body_guard = {

package/scripts/rules/rule-list.ts

@@ -2,53 +2,34 @@
 import { fileURLToPath } from 'node:url'
 import { delivered_rules } from './delivered-rules'
 import { guard_remedy } from './guard-remedy'
-import { rule_registry, type RegisteredRule } from './rule-registry'
+import { stop_rule_rows, type StopRule } from './stop-rule-rows'
 
 // `josh rule:list` — the list of trigger-delivered rules, rendered from the guard rows themselves.
 // One item per `MEASURED_RULES` row in delivery order, then the `Stop`
 // hook's rows; each carries its single source, the call it fires on and the turn it stays silent on.
-// The prose is `rule-registry.ts`; the order and the set are `delivered-rules.ts`, so a row added
-// there is listed without a document edit — and a row with no registry entry is listed as missing.
+// The prose is each row's own `about`, so a row added there is listed without a document edit.
 
 const HEADER =
 	'# Trigger-delivered rules — rendered by `pnpm josh rule:list` from `scripts/rules/delivered-rules.ts`'
-const MISSING = '(no entry in `scripts/rules/rule-registry.ts`)'
 const MISSING_WHY = '(no `why` in `scripts/rules/guard-remedy.ts`)'
 
-function item(id: string, rule: RegisteredRule | undefined): string {
-	if (rule === undefined) return `- \`${id}\` ${MISSING}`
-
+function item({ id, about }: StopRule): string {
 	return [
-		`- **${rule.title}** (\`${id}\`, ${rule.topic})`,
-		`  - fires: \`${rule.entry}\` — ${rule.fires}`,
-		`  - silent: ${rule.quiet}`,
+		`- **${about.title}** (\`${id}\`, ${about.topic})`,
+		`  - fires: \`${about.entry ?? delivered_rules.PRETOOL_GUARD}\` — ${about.fires}`,
+		`  - silent: ${about.quiet}`,
 		`  - not automated: ${guard_remedy.why_of(id) ?? MISSING_WHY}`,
 	].join('\n')
 }
 
-function row_ids(): ReadonlyArray<string> {
-	return delivered_rules.MEASURED_RULES.map((rule) => rule.id)
-}
-
 function render(): string {
-	const rows = row_ids().map((id) => item(id, rule_registry.entry_for(id)))
-	const stops = rule_registry.STOP_ROWS.map((rule) => item(rule.id, rule))
-
-	return [HEADER, '', ...rows, ...stops].join('\n')
-}
-
-// Registry entries no guard row reaches — a renamed or removed row left its prose behind.
-function orphans(): ReadonlyArray<string> {
-	const reached = new Set(row_ids().map((id) => rule_registry.registry_id(id)))
-	const stop_ids = new Set(rule_registry.STOP_ROWS.map((rule) => rule.id))
+	const rows = [...delivered_rules.MEASURED_RULES, ...stop_rule_rows.ROWS].map((rule) => item(rule))
 
-	return rule_registry.REGISTERED_RULES.map((rule) => rule.id).filter(
-		(id) => !reached.has(id) && !stop_ids.has(id),
-	)
+	return [HEADER, '', ...rows].join('\n')
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) process.stdout.write(`${render()}\n`)
 
-const rule_list = { MISSING, MISSING_WHY, orphans, render }
+const rule_list = { MISSING_WHY, render }
 
 export { rule_list }

package/scripts/rules/rule-value-cache.ts

@@ -1,7 +1,10 @@
 import { spawn } from 'node:child_process'
-import { mkdirSync, renameSync, statSync, writeFileSync } from 'node:fs'
+import { statSync } from 'node:fs'
 import path from 'node:path'
+import { git_common_directory } from '#scripts/git/git-common-directory'
+import { atomic_write } from '#scripts/lib/atomic-write'
 import { file_reader } from '#scripts/lib/read-file'
+import { MS_PER_MINUTE } from '#scripts/lib/timeouts'
 
 // The `rule:value` reading at the `backlogrun` loop head, without the loop waiting on it.
 // Measuring re-reads every transcript and takes minutes, and `backlog:offer`
@@ -12,30 +15,67 @@ import { file_reader } from '#scripts/lib/read-file'
 // **It reports and never fails**, as `rule:value` itself does: a missing cache, an unwritable directory
 // or a refresh that could not start prints at most nothing, and never changes the offer's answer.
 
-const CACHE_DIRECTORY = ['node_modules', '.cache', 'josh']
+// Outside a repository only: inside one the cache lives in the common git directory, so a lane's work
+// tree reads the reading its parent's loop head stored rather than measuring again
+// (joshuafolkken/kit#5186). The reading is the main checkout's — its transcripts and every lane's —
+// because only the main checkout writes it (`is_linked_work_tree`); a lane's own measurement reaches
+// only its own transcripts (`cost_transcript.transcript_directories`).
+const FALLBACK_DIRECTORY = ['node_modules', '.cache', 'josh']
 const CACHE_FILE = 'rule-value.txt'
 // Touched when a refresh starts, so the loop head starts at most one per interval however often it runs.
 const STAMP_FILE = 'rule-value.stamp'
-const MS_PER_MINUTE = 60_000
 const REFRESH_MINUTES = 15
 const REFRESH_MS = REFRESH_MINUTES * MS_PER_MINUTE
 const REFRESH_ARGV = ['josh', 'rule:value', '--refresh']
 const PNPM = 'pnpm'
-const TEMPORARY_SUFFIX = '.tmp'
 
 interface CachePorts {
 	now: () => number
 	start_refresh: (cwd: string) => void
 }
 
+interface FreshReading {
+	text: string
+	taken_at: Date
+}
+
 function cache_path(cwd: string, file: string): string {
-	return path.join(cwd, ...CACHE_DIRECTORY, file)
+	const common = git_common_directory.repository(cwd)
+
+	if (common === undefined) return path.join(cwd, ...FALLBACK_DIRECTORY, file)
+
+	return path.join(common, git_common_directory.STATE_DIRECTORY, file)
 }
 
 function read_cached(cwd: string): string | undefined {
 	return file_reader.read_if_readable(cache_path(cwd, CACHE_FILE))
 }
 
+function taken_at_if_fresh(cwd: string, now_ms: number): Date | undefined {
+	try {
+		const { mtime } = statSync(cache_path(cwd, CACHE_FILE))
+
+		return now_ms - mtime.getTime() < REFRESH_MS ? mtime : undefined
+	} catch {
+		return undefined
+	}
+}
+
+// The stored reading when it was taken inside the refresh interval — what `josh rule:value` prints
+// instead of measuring. `undefined` is a miss: no reading, or one older than the interval.
+function read_fresh(
+	cwd: string = process.cwd(),
+	now_ms: number = Date.now(),
+): FreshReading | undefined {
+	const taken_at = taken_at_if_fresh(cwd, now_ms)
+
+	if (taken_at === undefined) return undefined
+
+	const text = read_cached(cwd)
+
+	return text === undefined ? undefined : { text, taken_at }
+}
+
 function is_refresh_due(cwd: string, now_ms: number): boolean {
 	try {
 		return now_ms - statSync(cache_path(cwd, STAMP_FILE)).mtimeMs >= REFRESH_MS
@@ -45,12 +85,7 @@ function is_refresh_due(cwd: string, now_ms: number): boolean {
 }
 
 function write_cache_file(cwd: string, file: string, text: string): void {
-	const target = cache_path(cwd, file)
-	const temporary = `${target}${TEMPORARY_SUFFIX}`
-
-	mkdirSync(path.dirname(target), { recursive: true })
-	writeFileSync(temporary, text)
-	renameSync(temporary, target)
+	atomic_write.replace_file(cache_path(cwd, file), text)
 }
 
 function ignore_spawn_error(): void {
@@ -68,8 +103,14 @@ function start_refresh_default(cwd: string): void {
 
 const DEFAULT_PORTS: CachePorts = { now: Date.now, start_refresh: start_refresh_default }
 
+// A linked work tree — a lane — measures its own transcripts alone, so it never writes the main
+// checkout's reading or its stamp: either would stand in for the whole repository's for an interval.
+function is_linked_work_tree(cwd: string): boolean {
+	return git_common_directory.resolve(cwd) !== undefined
+}
+
 function refresh_if_due(cwd: string, ports: CachePorts): void {
-	if (!is_refresh_due(cwd, ports.now())) return
+	if (is_linked_work_tree(cwd) || !is_refresh_due(cwd, ports.now())) return
 
 	write_cache_file(cwd, STAMP_FILE, new Date(ports.now()).toISOString())
 	ports.start_refresh(cwd)
@@ -90,10 +131,12 @@ function emit(cwd: string = process.cwd(), ports: CachePorts = DEFAULT_PORTS): v
 
 // The detached refresh's body: the reading written whole, so a reader never sees half of one.
 function store(text: string, cwd: string = process.cwd()): void {
+	if (is_linked_work_tree(cwd)) return
+
 	write_cache_file(cwd, CACHE_FILE, `${text}\n`)
 }
 
-const rule_value_cache = { CACHE_FILE, REFRESH_MS, STAMP_FILE, cache_path, emit, store }
+const rule_value_cache = { CACHE_FILE, REFRESH_MS, STAMP_FILE, cache_path, emit, read_fresh, store }
 
-export type { CachePorts }
+export type { CachePorts, FreshReading }
 export { rule_value_cache }