@joshuafolkken/kit 1.1784.0 → 1.2116.0

package/scripts/rules/piped-verification-shapes.ts

@@ -0,0 +1,110 @@
+import { time_shell } from '#scripts/time-runtime/time-shell'
+import { time_transcript_line } from '#scripts/time-runtime/time-transcript-line'
+import { piped_verification } from './piped-verification'
+import { rule_value } from './rule-value'
+import { shell_segments } from './shell-segments'
+
+// The `piped-verification` refusals named by the filter that drew them, for `josh rule:value --fresh`.
+//
+// **Which shape to move from the refusal to the rewrite is read here, not in a transcript by hand.**
+// The refusal text is one fixed reason, so the row's `refused` count says how often and never why; the
+// command that drew it is the call the errored result answers, paired by its `tool_use_id`
+// (joshuafolkken/kit#5266). A shape is named by the first that holds, in the order below: the filters
+// that hide a verdict first, the chain — a line of more than one command, a heredoc's body lines
+// included — only where no filter explains the refusal.
+
+const SHAPE = {
+	head: 'head',
+	grep: 'grep',
+	script: 'awk|sed|tee',
+	chain: 'chain',
+	other: 'other',
+} as const
+
+type RefusalShape = (typeof SHAPE)[keyof typeof SHAPE]
+type ShapeCounts = Map<RefusalShape, number>
+
+const HEAD_FILTER = /^head\b/u
+const SCRIPT_FILTER = /^(?:awk|sed|tee)\b/u
+// The reason's opening, matched as `rule-value.ts` matches a refusal; a text without the cheap mark —
+// the reason's ASCII words, which the rewrite note does not share — is skipped unparsed.
+const SIGNATURE = piped_verification.PIPED_VERIFICATION_REASON.slice(
+	0,
+	rule_value.REASON_SIGNATURE_LENGTH,
+)
+const CHEAP_MARK = 'piped verification: a pipeline exits'
+const HEADING = 'piped-verification refusals by shape:'
+const SHAPE_GAP = ' · '
+
+function filter_shape(filters: ReadonlyArray<string>): RefusalShape | undefined {
+	if (filters.some((piece) => HEAD_FILTER.test(piece))) return SHAPE.head
+	if (filters.some((piece) => piped_verification.EARLY_EXIT_GREP.test(piece))) return SHAPE.grep
+
+	return filters.some((piece) => SCRIPT_FILTER.test(piece)) ? SHAPE.script : undefined
+}
+
+function shape_of(command: string): RefusalShape {
+	const by_filter = filter_shape(piped_verification.check_filters(command))
+
+	if (by_filter !== undefined) return by_filter
+
+	const segments = shell_segments.segments_of(time_shell.unquoted(command))
+
+	return segments.length > 1 ? SHAPE.chain : SHAPE.other
+}
+
+interface Pairing {
+	commands: Map<string, string>
+	refused: Array<string>
+}
+
+type Block = NonNullable<ReturnType<typeof time_transcript_line.parse_line>>['blocks'][number]
+
+function is_refusal(block: Block): boolean {
+	if (block.error_text === '') return false
+
+	return time_transcript_line.refusal_body(block.error_text).startsWith(SIGNATURE)
+}
+
+function pair_block(block: Block, pairing: Pairing): void {
+	if (block.id !== '') pairing.commands.set(block.id, time_shell.bash_command(block.input))
+	if (is_refusal(block)) pairing.refused.push(block.result_id)
+}
+
+function blocks_of(text: string): Array<Block> {
+	return text.split('\n').flatMap((line) => time_transcript_line.parse_line(line)?.blocks ?? [])
+}
+
+// The commands one transcript's `piped-verification` refusals answered.
+function refused_commands(text: string): Array<string> {
+	if (!text.includes(CHEAP_MARK)) return []
+
+	const pairing: Pairing = { commands: new Map(), refused: [] }
+
+	for (const block of blocks_of(text)) pair_block(block, pairing)
+
+	return pairing.refused
+		.map((id) => pairing.commands.get(id) ?? '')
+		.filter((command) => command !== '')
+}
+
+function count(text: string, counts: ShapeCounts): void {
+	for (const command of refused_commands(text)) {
+		const shape = shape_of(command)
+
+		counts.set(shape, (counts.get(shape) ?? 0) + 1)
+	}
+}
+
+function render(counts: ShapeCounts): string {
+	const cells = Object.values(SHAPE).map(
+		(shape) => `${shape} ${(counts.get(shape) ?? 0).toString()}`,
+	)
+
+	return `${HEADING} ${cells.join(SHAPE_GAP)}`
+}
+
+const piped_verification_shapes = { HEADING, SHAPE, count, refused_commands, render, shape_of }
+
+export { piped_verification_shapes }
+export type { RefusalShape, ShapeCounts }

package/scripts/rules/piped-verification.ts

@@ -40,6 +40,7 @@ import { shell_segments } from './shell-segments'
 // change. The Issue that filed this rule names `eval` for that reason.
 const VERIFICATION_COMMANDS: ReadonlySet<string> = new Set([
 	'check',
+	'check:related',
 	'cspell',
 	'cspell:dot',
 	'eval',
@@ -97,6 +98,13 @@ function pipelines_of(command: string): Array<Array<string>> {
 		.map((segment) => segment.split('|').map((piece) => piece.trim()))
 }
 
+// The filters behind each check on the line — what a refusal is named by (`piped-verification-shapes.ts`).
+function check_filters(command: string): Array<string> {
+	return pipelines_of(command).flatMap(([head = '', ...filters]) =>
+		is_verification_command(head) ? filters : [],
+	)
+}
+
 function command_pieces(command: string): Array<string> {
 	return pipelines_of(command).flat()
 }
@@ -125,7 +133,12 @@ function keeps_verdict_intact(command: string): boolean {
 // `grep` stopping at its first match — closes the pipe on a check still writing, and under `pipefail` the
 // check's SIGPIPE turns a passing run into exit 141; `head` also cuts the verdict line josh prints last.
 // `cut`, `sort`, `uniq` and `wc` read to the end as well, and a `grep … | cut -c1-250` narrowing was the
-// commonest masking still refused after #3875 (joshuafolkken/kit#3920).
+// commonest masking still refused after #3875 (joshuafolkken/kit#3920). `tee` passes every line on, and an
+// `awk` or `sed` script reads to the end where it can neither exit nor reach past the pipe — read on the
+// typed piece, since the script is quoted: an `awk` program with no `exit`, `nextfile`, `system`, `getline` or `|`,
+// and a `sed` script of `p`, `d` and `s///` alone (joshuafolkken/kit#5266). A quoted `<`, `>` or `&`
+// still refuses below: inside `awk` a `>` may be `print > "f"`, which no reading here tells from a
+// comparison.
 //
 // **Each masked check is wrapped on its own, and the rest of the line runs as typed.** Most of the
 // refusals left after #3570 were a check chained beside other work — `vitest …; pnpm josh lint:related
@@ -143,9 +156,18 @@ function keeps_verdict_intact(command: string): boolean {
 const PIPEFAIL_OPEN = '(set -o pipefail; '
 const PIPEFAIL_CLOSE = ')'
 const COMMENT_START = /(?:^|\s)#/u
-const FULL_READING_FILTER = /^(?:tail|grep|cut|sort|uniq|wc)\b/u
+const FULL_READING_FILTER = /^(?:tail|grep|cut|sort|uniq|wc|tee)(?=\s|$)/u
 const EARLY_EXIT_GREP =
 	/^grep\b.*\s(?:-[a-zA-Z]*[lLmq]|--(?:quiet|silent|max-count|files-with(?:out)?-match))/u
+const AWK_PROGRAM = /^awk\s+(?:-F\s*\S+\s+)?'[^']*'$/u
+const AWK_EARLY_EXIT = /\b(?:exit|nextfile|system|getline)\b|\|/u
+const SED_TEXT = String.raw`(?:[^/\\']|\\.)*`
+const SED_ADDRESS = String.raw`(?:\d+|\$|/${SED_TEXT}/)`
+const SED_COMMAND = String.raw`(?:${SED_ADDRESS}(?:,${SED_ADDRESS})?)?!?(?:p|d|s/${SED_TEXT}/${SED_TEXT}/[gip\d]*)`
+const SED_PROGRAM = new RegExp(
+	String.raw`^sed\s+(?:-[nEr]+\s+)*'${SED_COMMAND}(?:;\s*${SED_COMMAND})*'$`,
+	'u',
+)
 
 const ALLOWED_OPERATORS = /2>&1|&&/gu
 const SIDE_EFFECT_SYNTAX = /[&<>`]|\$\(/u
@@ -156,14 +178,40 @@ const PIPEFAIL_NOTE =
 	"`(set -o pipefail; …)` to carry the check's status, and the rest of the line ran as typed. Read " +
 	'the printed verdict, never the exit code alone — `prompts/collaboration-workflow/output-bounds.md`.'
 
-function reads_to_the_end(piece: string): boolean {
-	return FULL_READING_FILTER.test(piece) && !EARLY_EXIT_GREP.test(piece)
+function is_full_reading_script(typed: string): boolean {
+	if (AWK_PROGRAM.test(typed)) return !AWK_EARLY_EXIT.test(typed)
+
+	return SED_PROGRAM.test(typed)
 }
 
-function is_filtered_check(pipeline: Array<string>): boolean {
-	const [head = '', ...filters] = pipeline
+// A filter's name and flags are read on the blanked piece, its quoted script on the typed one.
+function reads_to_the_end(piece: string, typed: string): boolean {
+	if (FULL_READING_FILTER.test(piece)) return !EARLY_EXIT_GREP.test(piece)
 
-	return is_verification_command(head) && filters.every((piece) => reads_to_the_end(piece))
+	return is_full_reading_script(typed)
+}
+
+// The typed text at the offsets of the blanked pieces, each `gap` characters apart — the blanked line
+// keeps every offset, so a cut found there is the same cut in the typed one.
+function typed_slices(raw: string, pieces: ReadonlyArray<string>, gap: number): Array<string> {
+	const offset = { at: 0 }
+
+	return pieces.map((piece) => {
+		const typed = raw.slice(offset.at, offset.at + piece.length)
+
+		offset.at += piece.length + gap
+
+		return typed
+	})
+}
+
+function is_filtered_check(pieces: ReadonlyArray<string>, typed: ReadonlyArray<string>): boolean {
+	const [head = '', ...filters] = pieces.map((piece) => piece.trim())
+
+	return (
+		is_verification_command(head) &&
+		filters.every((piece, index) => reads_to_the_end(piece, typed[index + 1]?.trim() ?? ''))
+	)
 }
 
 function has_side_effect_syntax(command: string): boolean {
@@ -173,9 +221,13 @@ function has_side_effect_syntax(command: string): boolean {
 // The side-effect syntax is read on the typed part, since a double-quoted `$(cmd)` still runs; the pipe
 // cut and the grouping are read on the blanked one, since a quoted `|` or `(` is text.
 function is_rewritable_part(raw: string, judged: string): boolean {
-	const pipeline = judged.split('|').map((piece) => piece.trim())
+	const pieces = judged.split('|')
 
-	return !has_side_effect_syntax(raw) && !GROUP_SYNTAX.test(judged) && is_filtered_check(pipeline)
+	return (
+		!has_side_effect_syntax(raw) &&
+		!GROUP_SYNTAX.test(judged) &&
+		is_filtered_check(pieces, typed_slices(raw, pieces, 1))
+	)
 }
 
 // Where the part's code ends: an unquoted `#` opens a comment, which would swallow the closing `)`.
@@ -210,14 +262,10 @@ function pipefail_command(command: string): string | undefined {
 
 	if (judged === undefined || !is_masked_verification(command)) return undefined
 
-	const offset = { at: 0 }
-	const parts = shell_segments.parts_of(judged).map((part) => {
-		const raw = command.slice(offset.at, offset.at + part.length)
-
-		offset.at += part.length
-
-		return rewritten_part(raw, part)
-	})
+	const pieces = shell_segments.parts_of(judged)
+	const parts = typed_slices(command, pieces, 0).map((raw, index) =>
+		rewritten_part(raw, pieces[index] ?? ''),
+	)
 
 	const rewritten = parts.includes(undefined) ? undefined : parts.join('')
 
@@ -236,9 +284,11 @@ function pipefail_input(call: GuardedCall): Record<string, unknown> | undefined
 }
 
 const piped_verification = {
+	EARLY_EXIT_GREP,
 	PIPED_VERIFICATION_REASON,
 	PIPEFAIL_NOTE,
 	VERIFICATION_COMMANDS,
+	check_filters,
 	is_masked_verification,
 	keeps_verdict_intact,
 	pipefail_input,

package/scripts/rules/poll-loop.ts

@@ -1,5 +1,7 @@
 import { time_shell } from '#scripts/time-runtime/time-shell'
 import { bash_triggers } from './bash-triggers'
+import { early_heartbeat } from './early-heartbeat'
+import { shell_segments } from './shell-segments'
 
 // The trigger and the delivered text behind the `poll-loop` row of `delivered-rules.ts`.
 // The hand-written wait loop a lane child improvises over a backgrounded
@@ -23,8 +25,7 @@ import { bash_triggers } from './bash-triggers'
 // back on the run's self-restraint — the thing that let these loops through in the first place.
 
 // A `while` or `until` header, in either spelling a poll loop reaches for. The trailing whitespace is
-// what separates the keyword from a path that merely begins with it (`until.txt`); a `for` loop is out
-// by omission — it iterates a fixed list rather than probing a state.
+// what separates the keyword from a path that merely begins with it (`until.txt`).
 const LOOP_KEYWORD = /\b(?:while|until)\s/u
 // A `sleep` command with any argument — the pause between probes that makes a loop a poll rather than
 // a stream reader. Read anywhere in the line rather than at a command position, because the loop body
@@ -52,10 +53,72 @@ const PROBE_HEADERS: ReadonlyArray<RegExp> = [
 	String.raw`grep\s+-[A-Za-z]*q`,
 ].map((probe) => new RegExp(`${WHILE_HEADER}${probe}`, 'u'))
 
+// **A counted `for` that sleeps is a poll with a deadline** (joshuafolkken/kit#4800). A lane child
+// waited out a backgrounded reviewer with `for i in $(seq 1 30); do sleep 10; done`, and the
+// completion notification sat queued until the loop returned — the same held-back exit a `while` poll
+// costs, spelled as a count. A header that counts — `$(seq …)`, a `{1..N}` range, or `((…))` — has no
+// list to work through, so its `sleep` is the whole point. A `for` over a real list (`for f in *.ts`)
+// is ordinary work and passes, sleep or not. The `sleep` is read in the loop's body only — from the
+// header to its first `done` — so a counted loop beside an unrelated `sleep` is not a wait (review
+// round 1); a nested loop's inner `done` cuts the body short, which under-refuses and so fails safe.
+const COUNTED_FOR = new RegExp(
+	String.raw`${COMMAND_POSITION}for(?:\s*\(\(|\s+\w+\s+in\s+(?:\$\(\s*seq\b|\{\d+\.\.))`,
+	'u',
+)
+const THROUGH_FIRST_DONE = /^[\s\S]*?\bdone\b/u
+
+// **A sleep chain in front of a read is the same poll, unrolled** (joshuafolkken/kit#5115). A lane
+// child watched a backgrounded task with `sleep 20; sleep 20; sleep 20; tail -c 1500 …/x.output` and
+// `sleep 20; ps -p 123`: no loop keyword, so the rows above miss it, and a read segment makes it
+// work rather than a bare timer, so `early-heartbeat` stands down. Its sleep is only there for the
+// read after it, which the completion notification makes unnecessary. The call is cut where the shell
+// starts a program (`shell_segments.commands_of`), and every cut is a sleep, an inert marker
+// (`early-heartbeat`'s own reading of both), or a read of a file or a process — at least one read,
+// which is what keeps it disjoint from `early-heartbeat`'s bare timer. A short settle (`sleep 3; tail`)
+// is below the threshold and passes.
+const SETTLE_SECONDS = 10
+const NO_SECONDS = 0
+const READ_COMMAND = /^(?:tail|cat|head|ps|stat|grep|wc|ls|pgrep|test|kill\s+-0|\[\[?)(?=\s|$)/u
+
+function slept_seconds(segments: ReadonlyArray<string>): number {
+	return segments.reduce(
+		(total, segment) => total + (early_heartbeat.sleep_seconds(segment) ?? NO_SECONDS),
+		NO_SECONDS,
+	)
+}
+
+// Only the sleep in front of the first read counts: `tail x; sleep 20` reads first and waits after,
+// which is not a wait *for* the read.
+function is_sleep_then_read(plain: string): boolean {
+	const segments = shell_segments.commands_of(plain).filter((segment) => segment !== '')
+	const first_work = segments.findIndex((segment) => !early_heartbeat.is_wait_or_inert(segment))
+	const waited = first_work === -1 ? NO_SECONDS : slept_seconds(segments.slice(0, first_work))
+
+	if (waited < SETTLE_SECONDS) return false
+
+	return segments
+		.slice(first_work)
+		.every((segment) => early_heartbeat.is_wait_or_inert(segment) || READ_COMMAND.test(segment))
+}
+
 function is_state_wait(plain: string): boolean {
 	return UNTIL_HEADER.test(plain) || PROBE_HEADERS.some((header) => header.test(plain))
 }
 
+function is_counted_sleep(plain: string): boolean {
+	const header = COUNTED_FOR.exec(plain)
+
+	if (header === null) return false
+
+	const rest = plain.slice(header.index)
+
+	return SLEEP_COMMAND.test(THROUGH_FIRST_DONE.exec(rest)?.[0] ?? rest)
+}
+
+function is_sleeping_loop(plain: string): boolean {
+	return (LOOP_KEYWORD.test(plain) && SLEEP_COMMAND.test(plain)) || is_counted_sleep(plain)
+}
+
 // **A `while read … done < file` is a stream reader, not a poll**, even when its body sleeps to
 // throttle processing. Its condition consumes input rather
 // than probing for a state — a poll never reads its condition, it *tests* it (grep, wc, a file check)
@@ -80,18 +143,18 @@ function is_poll_loop(command: string): boolean {
 	if (is_stream_reader(plain)) return false
 	if (is_state_wait(plain)) return true
 
-	return LOOP_KEYWORD.test(plain) && SLEEP_COMMAND.test(plain)
+	return is_sleeping_loop(plain) || is_sleep_then_read(plain)
 }
 
 // The instruction in the shape a refusal can carry: why the command's exit is the thing to wait on,
 // and the one route that delivers that exit. The measurement behind it is in
 // `docs/maintainers/rule-delivery-rationale.md`.
 const POLL_LOOP_REASON =
-	"⛔ output poll loop: this hand-writes a `while`/`until` wait loop over a command's output, a " +
-	'marker file or a process, and the loop does not know when the command finished. Issue the long ' +
-	'command with `run_in_background` set and end the turn — its exit re-invokes you; for CI, ' +
-	'`pnpm josh followup` (`.claude/skills/workflow-commands/background-commands.md`). It fires on ' +
-	'every occurrence.'
+	'⛔ output poll loop: a `while`/`until` or counted `for` loop, or a `sleep` chain before a read, ' +
+	'does not know when the task finished. `run_in_background` and end the turn — its exit ' +
+	're-invokes you; a background `Agent` is waited on by its completion notification (lane child: ' +
+	'bare `sleep 20`, `pnpm josh run:liveness`); CI by `pnpm josh followup` ' +
+	'(`background-commands.md`). Fires on every occurrence.'
 
 // The row itself, so `delivered-rules.ts` spreads one entry. `decide` returns true so it refuses every
 // occurrence; it declares no `keeps` — waiting on the task exit is the *absence* of a loop, not a
@@ -106,7 +169,7 @@ const ROW = {
 		title: 'Output poll loop',
 		topic: '`.claude/skills/workflow-commands/background-commands.md`',
 		fires:
-			"a hand-written `while` / `until` wait loop over a command's output, a marker file or a process. Every occurrence",
+			"a hand-written `while` / `until` wait loop over a command's output, a marker file or a process, a counted `for` that sleeps, or a `sleep` chain of 10 s or more before a read of a file or process. Every occurrence",
 		quiet: 'the command started with `run_in_background` — its exit ends the wait',
 	},
 }

package/scripts/rules/pr-merge.ts

@@ -99,9 +99,9 @@ function is_pr_merge(command: string): boolean {
 const PR_MERGE_REASON =
 	'⛔ direct PR merge: `gh pr merge`, a `gh api` / `curl` call to `…/pulls/<N>/merge`, a ' +
 	'`mergePullRequest` / `enablePullRequestAutoMerge` mutation, or a GraphQL body read from a file ' +
-	'merges outside the verified route, and a merge is Tier C. Merge with `pnpm josh followup` when the ' +
-	'run authorizes it; otherwise leave it to the user (`CLAUDE.md` → Git Rules). This rule fires on ' +
-	'every occurrence.'
+	'merges outside the verified route, and a merge is Tier C. Merge with `pnpm josh followup` if the ' +
+	'run authorizes it; otherwise leave it to the user (`operating-rules.md` → git-rules). This rule ' +
+	'fires on every occurrence.'
 
 const ROW = {
 	id: 'pr-merge',
@@ -110,7 +110,7 @@ const ROW = {
 	decide: (): boolean => true,
 	about: {
 		title: 'Direct PR merge',
-		topic: '`CLAUDE.md` → Git Rules',
+		topic: '`operating-rules.md` → "git-rules"',
 		fires:
 			'`gh pr merge`, a `gh api` / `curl` call to `…/pulls/<N>/merge`, a `mergePullRequest` / `enablePullRequestAutoMerge` mutation, or a GraphQL body read from a file. Every occurrence',
 		quiet:
@@ -118,6 +118,6 @@ const ROW = {
 	},
 }
 
-const pr_merge = { PR_MERGE_REASON, ROW, is_pr_merge }
+const pr_merge = { PR_MERGE_REASON, ROW, is_graphql_call, is_pr_merge }
 
 export { pr_merge }

package/scripts/rules/pre-gate-cut.ts

@@ -139,7 +139,7 @@ function uncut_lane_issue(state: LaneCutState): string | undefined {
 }
 
 // **The cut is taken only when the current context is worth its resume**.
-// Below the shared `CONTEXT_CUT_THRESHOLD` a short lane has no accumulation a cut would drop, so the
+// Below the model-priced `pnpm josh cost --cut` threshold a short lane has no accumulation a cut would drop, so the
 // gate runs uncut rather than paying for a relaunch; an unmeasurable session keeps the old
 // unconditional cut as the safety net. The verdict is
 // `cost_cli.session_verdict`'s, the same statistic and threshold `run:cut` and the implementation-phase
@@ -163,8 +163,8 @@ function is_uncut_gate(command: string, state: LaneCutState = current_state()):
 const PRE_GATE_CUT_REASON =
 	'⛔ pre-gate cut: this checkout is a lane dispatched for this issue and the gate is the boundary to ' +
 	'cut at. Issue `pnpm josh run:cut <N>`: on `cut`, end the turn immediately — no Telegram is owed; ' +
-	'on any other verdict (`not-a-lane`, `busy`, …), reissue the gate — this fires once per run ' +
-	'(`.claude/skills/workflow-commands/pre-gate-cut.md`).'
+	'on `split-unresolved`, answer its notice and rerun it; on any other verdict (`not-a-lane`, `busy`, …), ' +
+	'reissue the gate — this fires once per run (`.claude/skills/workflow-commands/pre-gate-cut.md`).'
 
 // **The pre-gate cut is two acts, one call apart**, so its `rule:value`
 // denominator is only the runs that reached the boundary: a run that issues the cut's entry check and,

package/scripts/rules/protected-files.ts

@@ -2,7 +2,9 @@ import path from 'node:path'
 import { doctor_consumer } from '#scripts/doctor/doctor-consumer'
 import { json_value } from '#scripts/lib/json-value'
 import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
+import { time_shell } from '#scripts/time-runtime/time-shell'
 import { bash_triggers } from './bash-triggers'
+import { edit_tool } from './edit-tool'
 import { git_argv } from './git-argv'
 import { shell_segments } from './shell-segments'
 
@@ -22,7 +24,7 @@ import { shell_segments } from './shell-segments'
 // It fires on every occurrence, for the reason `git-force.ts` does.
 
 const READ_TOOL = 'Read'
-const EDIT_TOOLS: ReadonlySet<string> = new Set(['Edit', 'Write'])
+const { is_edit_tool } = edit_tool
 const SECRET_FILES: ReadonlySet<string> = new Set(['.env', '.dev.vars'])
 const ENVIRONMENT_VARIANT_PREFIX = '.env.'
 // The two variants `.gitignore` un-ignores: they are tracked and hold placeholders, not secrets. The
@@ -31,10 +33,22 @@ const TRACKED_VARIANTS: ReadonlySet<string> = new Set(['.env.example', '.env.tes
 const SETTINGS_FILE = path.join('.claude', 'settings.json')
 const WHITESPACE = /\s+/u
 const TOKEN_QUOTES = /["']/gu
-const INPUT_REDIRECT = '<'
-// Programs that print a named file's bytes, or run them. `cp` and `mv` are deliberately absent: they
-// write rather than print, and `cp .env.example .env` is how a checkout's `.env` is made.
-const SHELL_READERS: ReadonlySet<string> = new Set([
+// Each character of a redirect operator (`<`, `>`, `>>`, `2>`, `&>`) — and the clobber `>|` whole —
+// is spaced out to a mark, so the word after the last one is the file it reads or writes.
+const REDIRECT = />\||[<>]/gu
+const REDIRECT_MARK = '<'
+// Programs that run their quoted argument as a script.
+const SHELLS: ReadonlySet<string> = new Set(['bash', 'eval', 'sh', 'zsh'])
+// The body of a `$(…)` (innermost) or a backtick command substitution.
+const SUBSTITUTION = /\$\((?<dollar>[^()]*)\)|`(?<backtick>[^`]*)`/gu
+// Programs that print a named file's bytes or run them, and programs that write one: a write could set
+// a guard switch, so `cp .env.example .env` is refused too (kit #4660) — the person makes the file.
+const SHELL_PROGRAMS: ReadonlySet<string> = new Set([
+	'cp',
+	'install',
+	'ln',
+	'mv',
+	'tee',
 	'.',
 	'awk',
 	'base64',
@@ -88,33 +102,82 @@ function is_environment_path(token: string): boolean {
 	return SECRET_FILES.has(name) || name.startsWith(ENVIRONMENT_VARIANT_PREFIX)
 }
 
-// A shell read reaches the same bytes a `Read` does, so a segment that runs a reader (`cat .env`,
-// `source .env`) or redirects the file into a command (`< .env`) is refused too. Claude Code applies
-// the `Read` deny rules to the readers it recognizes, but `source .env.local` passes them (measured on
-// 2.1.289, kit #3602), so the variants are matched here as well.
-function is_environment_read_segment(segment: string): boolean {
-	const words = segment
-		.replaceAll(INPUT_REDIRECT, ' < ')
+// A shell read reaches the same bytes a `Read` does, and a shell write changes the file an `Edit`
+// would, so a segment that runs one of the programs (`cat .env`, `source .env`, `tee .env`) or
+// redirects the file (`< .env`, `>> .env`) is refused too. Claude Code applies the `Read` deny rules to
+// the readers it recognizes, but `source .env.local` passes them (measured on 2.1.289, kit #3602), so
+// the variants are matched here as well.
+//
+// A quoted `>` is text (`git commit -m "x >> .env"`), so the marks are read on the quote-blanked
+// segment, whose offsets match the original; a shell's quoted script (`sh -c "echo x > .env"`) runs,
+// so its marks are read as written, as is a heredoc line, which `blanked` does not cut.
+function redirect_marks_of(segment: string, program: string | undefined): string {
+	if (program !== undefined && SHELLS.has(program)) return segment
+
+	return time_shell.blanked(segment) ?? segment
+}
+
+function spaced_redirects(segment: string, program: string | undefined): string {
+	const marks = redirect_marks_of(segment, program)
+
+	return segment.replaceAll(REDIRECT, (mark, offset: number) =>
+		marks.startsWith(mark, offset) ? ` ${REDIRECT_MARK} ` : mark,
+	)
+}
+
+function is_environment_shell_segment(segment: string): boolean {
+	const call = git_argv.program_of(segment)
+	const words = spaced_redirects(segment, call?.name)
 		.split(WHITESPACE)
 		.filter((word) => word !== '')
 	const is_redirected = words.some(
-		(word, index) => word === INPUT_REDIRECT && is_environment_path(words[index + 1] ?? ''),
+		(word, index) => word === REDIRECT_MARK && is_environment_path(words[index + 1] ?? ''),
 	)
-	const call = git_argv.program_of(segment)
 
 	if (is_redirected || call === undefined) return is_redirected
 
-	return SHELL_READERS.has(call.name) && call.args.some((word) => is_environment_path(word))
+	return SHELL_PROGRAMS.has(call.name) && call.args.some((word) => is_environment_path(word))
+}
+
+// A shell's quoted script holds commands of its own (`bash -c "true; cat .env"`), so it is cut again
+// without regard to quotes.
+function script_commands_of(segment: string): Array<string> {
+	const program = git_argv.program_of(segment)?.name
+
+	if (program === undefined || !SHELLS.has(program)) return []
+
+	return shell_segments.commands_of(segment)
+}
+
+// A command substitution runs even inside double quotes (`echo "$(echo x > .env)"`), which the
+// quote-blanked reading takes for text, so its body is cut out as commands of their own.
+function substitution_commands_of(segment: string): Array<string> {
+	return [...segment.matchAll(SUBSTITUTION)].flatMap((match) =>
+		shell_segments.commands_of(match.groups?.['dollar'] ?? match.groups?.['backtick'] ?? ''),
+	)
+}
+
+function segments_of(command: string): Array<string> {
+	return shell_segments
+		.quote_aware_commands_of(command)
+		.flatMap((segment) => [
+			segment,
+			...script_commands_of(segment),
+			...substitution_commands_of(segment),
+		])
 }
 
-function is_environment_shell_read(command: string): boolean {
-	return shell_segments.commands_of(command).some((segment) => is_environment_read_segment(segment))
+function is_environment_shell_access(command: string): boolean {
+	return segments_of(command).some((segment) => is_environment_shell_segment(segment))
 }
 
-function is_environment_read(call: GuardedCall): boolean {
-	if (call.name === READ_TOOL) return is_environment_path(file_path_of(call))
+// A `Read` lands the secret in the transcript; an `Edit` / `Write` could set a guard switch.
+function is_environment_access(call: GuardedCall): boolean {
+	if (call.name === READ_TOOL || is_edit_tool(call.name)) {
+		return is_environment_path(file_path_of(call))
+	}
 
-	return bash_triggers.on_bash_command(is_environment_shell_read)(call)
+	return bash_triggers.on_bash_command(is_environment_shell_access)(call)
 }
 
 // The repository the settings file belongs to is two levels above it (`<root>/.claude/settings.json`).
@@ -122,7 +185,7 @@ function is_consumer_settings_edit(
 	call: GuardedCall,
 	is_kit_consumer: (root: string) => boolean,
 ): boolean {
-	if (!EDIT_TOOLS.has(call.name)) return false
+	if (!is_edit_tool(call.name)) return false
 
 	const file_path = path.resolve(file_path_of(call))
 
@@ -135,11 +198,12 @@ function is_protected_file_call(
 	call: GuardedCall,
 	is_kit_consumer: (root: string) => boolean = doctor_consumer.is_kit_consumer,
 ): boolean {
-	return is_environment_read(call) || is_consumer_settings_edit(call, is_kit_consumer)
+	return is_environment_access(call) || is_consumer_settings_edit(call, is_kit_consumer)
 }
 
 const PROTECTED_FILE_REASON =
-	'⛔ protected file: `.env`, a `.env.*` variant and `.dev.vars` hold secrets, and a consumer ' +
+	'⛔ protected file: `.env`, a `.env.*` variant and `.dev.vars` hold secrets and are written only ' +
+	'by the person, and a consumer ' +
 	'`.claude/settings.json` is owned by `josh sync` (a change belongs upstream in kit). Leave these ' +
 	'files alone, or ask the user. It fires on every occurrence.'
 
@@ -154,7 +218,7 @@ const ROW = {
 		title: 'Protected file',
 		topic: '`operating-rules.md`',
 		fires:
-			'a `Read` of `.env`, or an `Edit` / `Write` of `.claude/settings.json` outside kit. Every occurrence',
+			'a `Read`, `Edit` or `Write` of `.env` (or a shell read or write of it), or an `Edit` / `Write` of `.claude/settings.json` outside kit. Every occurrence',
 		quiet: "kit itself, or the user's `~/.claude/settings.json`",
 	},
 }

package/scripts/rules/reply-language.ts

@@ -1,3 +1,5 @@
+import { reply_prose } from './reply-prose'
+
 // Whether a reply is written in the session language. The session-language
 // line reaches a turn only through `UserPromptSubmit`, so a turn opened by a background completion or a
 // Stop hook refusal answered in whatever language it was just shown, and kept answering in it.
@@ -31,14 +33,6 @@ const MATCH_SHARE_FLOOR = 0.5
 // unless no line of the reply is longer.
 const MIN_VOTING_LETTERS = 8
 
-const CODE_PATTERNS: ReadonlyArray<RegExp> = [
-	/```[\s\S]*?(?:```|$)/gu,
-	/`[^`\n]*`/gu,
-	/\]\([^)\s]*\)/gu,
-	/https?:\/\/\S+/gu,
-]
-// A run of printable ASCII; one holding a slash is a bare path the reply printed outside backticks.
-const ASCII_RUN_PATTERN = /[!-~]+/gu
 const LETTER_PATTERN = /\p{L}/gu
 // A letter of another script — `Common` and `Inherited` letters (`µ`) belong to no language of their own.
 const NON_LATIN_LETTER_PATTERN = /(?![\p{Script=Latn}\p{Script=Common}\p{Script=Inherited}])\p{L}/u
@@ -63,14 +57,6 @@ function letter_pattern(script: string): RegExp | undefined {
 	}
 }
 
-function prose_of(message: string): string {
-	let text = message
-
-	for (const pattern of CODE_PATTERNS) text = text.replaceAll(pattern, ' ')
-
-	return text.replaceAll(ASCII_RUN_PATTERN, (run) => (run.includes('/') ? ' ' : run))
-}
-
 function letter_count(text: string): number {
 	return text.match(LETTER_PATTERN)?.length ?? 0
 }
@@ -105,7 +91,7 @@ function is_mismatch(message: string, lang: string): boolean {
 	const pattern = letter_pattern(script)
 	if (pattern === undefined) return false
 
-	const prose = prose_of(message)
+	const prose = reply_prose.prose_of(message)
 	if (letter_count(prose) < MIN_PROSE_LETTERS) return false
 
 	return matches_share(prose, script, pattern) < MATCH_SHARE_FLOOR