@joshuafolkken/kit 1.1166.0 → 1.1229.0

package/scripts/rules/git-force.ts

@@ -15,7 +15,7 @@ import { shell_segments } from './shell-segments'
 //
 // **It fires on every occurrence, not once per run.** A force push is destructive every time it is
 // issued, so refused-once-and-free-after would put the second one back on the run's self-restraint —
-// the disposition `run-tail.ts` and `filing-cap.ts` take for the same reason.
+// the disposition `run-tail-rule.ts` and `filing-cap.ts` take for the same reason.
 
 // A force push. The long forms all open with `--force` (`--force`, `--force-with-lease[=ref]`,
 // `--force-if-includes`); `-f` and any cluster carrying `f` are the short forms; a bare `--delete` and

package/scripts/rules/implementation-cut.ts

@@ -5,8 +5,8 @@ import { cost_verdict } from '#scripts/cost-runtime/cost-verdict'
 import type { GuardRun } from '#scripts/josh/hook-decision'
 import { lane_child_marker, type MarkerSource } from '#scripts/lane/lane-child-marker'
 import { lane_paths } from '#scripts/lane/lane-paths'
-import { run_cut, type RunCut } from '#scripts/run/run-cut'
-import { run_cut_handoff } from '#scripts/run/run-cut-handoff'
+import { run_cut, type RunCut } from '#scripts/run/cut/run-cut'
+import { run_cut_handoff } from '#scripts/run/cut/run-cut-handoff'
 import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
 import { bash_triggers } from './bash-triggers'
 import { implementation_cut_verdict } from './implementation-cut-verdict'

package/scripts/rules/index-guard.ts

@@ -52,7 +52,7 @@ function is_index_mutation(command: string): boolean {
 const INDEX_MUTATION_REASON =
 	'⛔ git index mutation: `git add` / `stage` / `commit` / `reset` / `rm` / `mv` and `git restore ' +
 	"--staged` overwrite the user's staged snapshot, which `CLAUDE.md` → Git Rules forbids on your own " +
-	'judgement (`prompts/collaboration-workflow/operating-rules.md` → "git index を勝手に変更しない"). The ' +
+	'judgement (`prompts/collaboration-workflow/operating-rules.md` → "no-self-staging"). The ' +
 	'`.claude/settings.json` deny list matches prefix globs, so it misses `git -C . commit`, `git -c ' +
 	'k=v commit` and `env git commit`; this row reads the argv instead, so the spelling does not matter. ' +
 	'A commit goes through `pnpm josh git -y`; any other staging needs explicit current-turn user ' +

package/scripts/rules/issue-comments.ts

@@ -0,0 +1,118 @@
+import { bash_triggers } from './bash-triggers'
+import { gh_api } from './gh-api'
+import { prior_comment_read } from './prior-comment-read'
+import { shell_segments } from './shell-segments'
+
+// The trigger and the delivered text behind the `issue-comments` row of `delivered-rules.ts`, moved
+// out of the enumeration so the list stays a list (joshuafolkken/kit#3264).
+
+// **A shell line carries several commands, and the subcommand has to be the one being invoked.**
+// Each segment is judged on its own, anchored at its start, so `gh issue comment <N> -b "… gh issue
+// view <N> …"` is read as the write it is rather than as the read it quotes. The cut itself is
+// `shell-segments.ts`, shared with the triggers that need the same one.
+// Global flags may precede the subcommand (`gh --repo o/r issue view 1`), so they are skipped —
+// the same optional-flag prefix `gh-api.ts` skips in front of `api`, shared from there.
+const ISSUE_VIEW_COMMAND = new RegExp(String.raw`^gh\s+${gh_api.GH_FLAGS}issue\s+view\s`, 'u')
+// `…/issues/<N>` — **one** Issue's body. The number has to end the path, so the listing
+// (`…/issues`) and every sub-resource under it (`…/issues/1319/comments`) are left alone.
+const ISSUE_BODY_PATH = /repos\/[^\s'"]*\/issues\/\d+(?=$|["'\s])/u
+// **A write to that path is not a read of it**, which is why the body read below asks `gh_api.is_read`:
+// `gh api` sends POST as soon as any field flag appears, and `kickoff` PATCHes `…/issues/<N>` to
+// normalize a title and to fill a blank body — so without the read check the delivery would be spent
+// refusing a write, and the genuine body read later in the same run would never be guarded.
+// A segment that fetches comments: the flag, a `comments` field in a `--json` projection, or the
+// comments endpoint. The short `-c` is deliberately absent — it belongs to `wc`, `grep` and `sort`
+// far more often than to `gh`, and reading it as "comments included" silenced the rule on any line
+// that ended in a pipe. A run that types it pays one round trip instead.
+const FETCHES_COMMENTS = /--comments\b|--json\s[\w,]*\bcomments\b|\/comments\b/u
+const ISSUES_PATH = /repos\/[^\s'"]*\/issues\//u
+
+// A field projection — `--jq` for `gh api`, `--json` for `gh issue view` — whose value never names the
+// body. `gh api …/issues/<N> --jq '{state, labels}'` fetches the Issue only to read its state or its
+// labels, which is a state check and not the body read this rule guards (joshuafolkken/kit#1905); a
+// `--jq '.body'` still names the body and stays a body read. The value is taken quoted or bare, so the
+// comma list `--json state,labels` and the expression `'{state, labels}'` are read the same way.
+const FIELD_PROJECTION = /(?:--jq|--json)[= ]\s*('[^']*'|"[^"]*"|\S+)/u
+const NAMES_THE_BODY = /\bbody\b/u
+
+function projects_away_body(segment: string): boolean {
+	const projection = FIELD_PROJECTION.exec(segment)
+
+	return projection !== null && !NAMES_THE_BODY.test(projection[1] ?? '')
+}
+
+function is_body_read_segment(segment: string): boolean {
+	if (projects_away_body(segment)) return false
+
+	if (ISSUE_VIEW_COMMAND.test(segment)) return true
+
+	return gh_api.is_gh_api(segment) && ISSUE_BODY_PATH.test(segment) && gh_api.is_read(segment)
+}
+
+// **An Issue's comments, not just any comments.** Batching pushes a run to fetch the body and the
+// comments on one line, so the allowance has to reach across segments — but `gh pr view 42 --json
+// comments` says nothing about whether *this* Issue was read whole, so the segment doing the
+// fetching has to be an Issue read itself.
+function fetches_issue_comments(segment: string): boolean {
+	if (!FETCHES_COMMENTS.test(segment)) return false
+
+	return (
+		ISSUE_VIEW_COMMAND.test(segment) || (gh_api.is_gh_api(segment) && ISSUES_PATH.test(segment))
+	)
+}
+
+// **The trigger is the body read, not the start of implementation.** The moment an Issue's body
+// reaches a run is the moment the rule binds, and it is one shell call — the test
+// `prompts/collaboration-workflow/rule-delivery.md` sets for leaving residency.
+function is_body_only_issue_read(command: string): boolean {
+	const segments = shell_segments.segments_of(command)
+
+	if (segments.some((segment) => fetches_issue_comments(segment))) return false
+
+	return segments.some((segment) => is_body_read_segment(segment))
+}
+
+// **Keeping the comments rule is fetching them**, in any of the spellings the refusal hands back.
+function reads_issue_comments(command: string): boolean {
+	return shell_segments.segments_of(command).some((segment) => fetches_issue_comments(segment))
+}
+
+// **The refusal hands over the command that fixes it**, because reading is not the same as
+// obeying: a sentence saying "also read the comments" is prose of exactly the kind
+// joshuafolkken/kit#1344 measured as moving nothing, while a refused body read leaves the run
+// holding the reissue that makes the comments *present*. The conflict rule ships with it — a
+// delivery that said only "read them" would hand back the deciding at the moment nothing else is
+// open to read, the mistake joshuafolkken/kit#1518 corrected for the WIP cap.
+const ISSUE_COMMENTS_REASON =
+	"⛔ an Issue's comments are part of the Issue: read them before implementing, not only the body. " +
+	'A decision recorded after the body was written lives only in a comment — a corrected diagnosis ' +
+	'(joshuafolkken/kit#1537), a changed default and an added acceptance criterion ' +
+	'(joshuafolkken/kit#1520), a scope handed to another Issue (joshuafolkken/kit#1304) — and ' +
+	'nothing in the body says it was superseded, so a body-only reader builds the wrong thing and ' +
+	'sees no contradiction. Reissue this read with the comments included: ' +
+	"`gh api repos/{owner}/{repo}/issues/<N>/comments --jq '.[] | {user: .user.login, created_at, " +
+	"body}'` beside the body read, or `gh issue view <N> --comments` where GraphQL is reachable. " +
+	'Then the later text is the agreement in force — a comment supersedes the body it contradicts — ' +
+	"except for two answers that are not the run's to make: work a comment reassigns to another " +
+	'Issue is out of scope and is not implemented, and a comment saying the Issue no longer has a ' +
+	'reason to exist stops the run with a `confirmation` Telegram. The procedure is ' +
+	'`.claude/skills/workflow-commands/issue-comments.md`. ' +
+	'Every body-only read is refused until the comments are read.'
+
+// The enumeration row itself, so `delivered-rules.ts` spreads one entry. `already_satisfied` stands it
+// down once the comments are on the transcript tail, and until then it refuses every body-only read.
+const ROW = {
+	id: 'issue-comments',
+	is_trigger: bash_triggers.on_bash_command(is_body_only_issue_read),
+	reason: ISSUE_COMMENTS_REASON,
+	already_satisfied: prior_comment_read.already_read_for_call,
+	keeps: bash_triggers.on_bash_command(reads_issue_comments),
+}
+
+const issue_comments = {
+	ISSUE_COMMENTS_REASON,
+	ROW,
+	is_body_only_issue_read,
+}
+
+export { issue_comments }

package/scripts/rules/{issue-fold.ts → issue-fold-rule.ts}

@@ -67,6 +67,6 @@ const ROW = {
 	keeps: bash_triggers.on_bash_command(runs_the_fold),
 }
 
-const issue_fold = { ISSUE_FOLD_REASON, ROW, already_folded, runs_the_fold }
+const issue_fold_rule = { ISSUE_FOLD_REASON, ROW, already_folded, runs_the_fold }
 
-export { issue_fold }
+export { issue_fold_rule }

package/scripts/rules/lane-background.ts

@@ -7,7 +7,7 @@ import {
 	time_transcript_line,
 	type Block as TranscriptBlock,
 } from '#scripts/time-runtime/time-transcript-line'
-import { run_tail } from './run-tail'
+import { run_tail_rule } from './run-tail-rule'
 
 // A dispatched lane child is stopped from backgrounding a long-running josh command (joshuafolkken/kit#2704).
 //
@@ -85,7 +85,7 @@ function is_backgrounded_ship(call: GuardedCall): boolean {
 // detached route on its first refusal rather than two contradictory ones. A backgrounded `ship` alone is
 // not refused: `foreground_input` turns it into the foreground call the refusal used to ask for.
 function is_candidate(call: GuardedCall): boolean {
-	if (run_tail.is_push_step_call(call)) return true
+	if (run_tail_rule.is_push_step_call(call)) return true
 
 	const command = backgrounded_bash_command(call)
 

package/scripts/rules/lane-park.ts

@@ -1,6 +1,7 @@
 import { NEEDS_DECISION_LABEL } from '#scripts/issue/issue-labels'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
 import { lane_handoff } from '#scripts/lane/lane-handoff'
+import { bash_triggers } from './bash-triggers'
 import { shell_segments } from './shell-segments'
 
 // A dispatched lane child records its park before it stops, delivered at the call it binds on
@@ -124,9 +125,26 @@ const LANE_PARK_REASON =
 	'procedure is `.claude/skills/workflow-commands/pre-gate-cut.md` → "A lane child records its park ' +
 	'before it stops", and the park itself is `backlogrun-park.md` → "park and continue".'
 
+// The row itself, so `delivered-rules.ts` spreads one entry. **Once per run rather than `decide`, and
+// no `already_satisfied`.** The stop ends the turn, so it is not the recurring act joshuafolkken/kit#1570
+// wrote `decide` for. It carries no `already_satisfied` because the park it asks for is a GitHub label a
+// synchronous guard cannot read, and the transcript-tail alternative would read a child that merely
+// *read* `backlogrun-park.md` — whose prose carries the `labels[]=needs-decision` command — as
+// compliant and fall silent on a real violation (the header above). `keeps` reads an actual
+// label-application `Bash` command, never the tail, so it is not fooled the same way; `reaches` stays
+// `is_trigger`, since a compliant run issues the same confirmation notify and belongs in the
+// denominator.
+const ROW = {
+	id: 'lane-park',
+	is_trigger: bash_triggers.on_bash_command(is_unparked_stop),
+	reason: LANE_PARK_REASON,
+	keeps: bash_triggers.on_bash_command(records_the_park),
+}
+
 const lane_park = {
 	COMMAND_NOTIFY_MARKER,
 	LANE_PARK_REASON,
+	ROW,
 	is_confirmation_notify,
 	is_parking_child,
 	is_unparked_stop,

package/scripts/rules/lane-split-park.ts

@@ -0,0 +1,128 @@
+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 { bash_triggers } from './bash-triggers'
+import { lane_park } from './lane-park'
+import { shell_segments } from './shell-segments'
+import { tail_commands } from './tail-commands'
+
+// A dispatched lane child that split its own Issue is stopped from parking the epic it promoted
+// (joshuafolkken/kit#3296).
+//
+// **A split is not a park.** On 2026-10-06, inside a `backlogrun`, the lane child for #3255 promoted
+// its Issue to an epic with `pnpm josh epic --promote 3255`, filed #3291–#3294, then applied
+// `needs-decision` to #3255 and sent a `confirmation` Telegram asking whether to run the epic. The
+// children were already opted in, so the question had no answer to wait for, and the same run's child
+// for #3247 had split without parking. `backlogrun-park.md` → "Splitting a child mid-run" says
+// splitting alone never adds `needs-decision` to the promoted epic; the parent reads an open Issue that
+// carries `epic` as a split (`run-merge.ts`), so the label is never what tells it.
+//
+// **The material is the run's own calls.** The promotion is a `josh epic --promote <N>` this run issued,
+// read off the transcript tail as `filing-cap.ts` reads its filings — a tool call, never prose, so a
+// child that merely read a document quoting the command is not mistaken for one that ran it. Only a
+// promotion of the dispatched issue counts: the epic a mid-run split promotes is the child's own Issue.
+
+// `josh epic`, named canonically — `shell_segments.is_josh_command` expands an alias before the match.
+const EPIC_COMMANDS: ReadonlySet<string> = new Set(['epic'])
+const PROMOTED_ISSUE = /--promote[=\s]+["']?(?<issue>\d+)\b/u
+// The issue a label write targets, in the two spellings `lane_park.records_the_park` accepts: the REST
+// path `…/issues/<N>/labels` and `gh issue edit <N>`.
+const LABEL_TARGETS: ReadonlyArray<RegExp> = [
+	/\/issues\/(?<issue>\d+)\/labels\b/u,
+	/\bissue\s+edit\s+["']?(?<issue>\d+)\b/u,
+]
+// The issue a confirmation notify is about, read off its `--issue-url` the way `stop-rules.ts` spells it.
+const ISSUE_URL = /--issue-url[=\s]+["']?([^\s"']+)/u
+const URL_ISSUE = /\/issues\/(\d+)\b/u
+
+function promoted_in(segment: string): string | undefined {
+	if (!shell_segments.is_josh_command(segment, EPIC_COMMANDS)) return undefined
+
+	return PROMOTED_ISSUE.exec(segment)?.groups?.['issue']
+}
+
+// Every issue a `josh epic --promote` among these commands promoted.
+function promoted_issues(commands: ReadonlyArray<string>): ReadonlySet<string> {
+	const segments = commands.flatMap((command) => shell_segments.segments_of(command))
+	const issues = segments.map((segment) => promoted_in(segment))
+
+	return new Set(issues.filter((issue) => issue !== undefined))
+}
+
+function label_target(command: string): string | undefined {
+	for (const pattern of LABEL_TARGETS) {
+		const issue = pattern.exec(command)?.groups?.['issue']
+
+		if (issue !== undefined) return issue
+	}
+
+	return undefined
+}
+
+// **Both acts of the park are refused: the label write and the stop Telegram.** Refusing the label
+// alone left the notify to `lane-park`, whose once-per-run refusal asks for this very label and lets the
+// reissue through, so the Telegram still went out. This row is listed before `lane-park` and shares the
+// notify with it — an overlap that is safe because a run that promoted nothing is left to `lane-park`
+// (`decide` answers false and the call falls through). Either act onto another issue — the leftover
+// child the procedure does park — is not the epic's park, so it is left alone.
+function is_park_of(command: string, issue: string): boolean {
+	return lane_park.records_the_park(command) && label_target(command) === issue
+}
+
+function notified_issue(command: string): string | undefined {
+	const [, url = ''] = ISSUE_URL.exec(command) ?? []
+	const [, issue] = URL_ISSUE.exec(url) ?? []
+
+	return issue
+}
+
+function is_notify_of(command: string, issue: string): boolean {
+	return lane_park.is_confirmation_notify(command) && notified_issue(command) === issue
+}
+
+// **The command test comes first and the world is consulted second**, exactly as `lane-park.ts` gates
+// its own read: a person working in a lane carries no mark and sees no refusal.
+function is_candidate(command: string): boolean {
+	const issue = lane_child_marker.marked_issue()
+
+	if (issue === undefined) return false
+	if (!is_park_of(command, issue) && !is_notify_of(command, issue)) return false
+
+	return lane_child_marker.is_child_of(process.cwd())
+}
+
+// Refused only once the run has promoted the dispatched issue, and on every occurrence: a split child
+// must never park its epic, so the route is always "return the split", never a reissue.
+function decide(_call: unknown, run: GuardRun): boolean {
+	const issue = lane_child_marker.marked_issue()
+	const commands = tail_commands.prior_bash_commands(time_density_hook.read_tail(run.transcript))
+
+	return issue !== undefined && promoted_issues(commands).has(issue)
+}
+
+const LANE_SPLIT_PARK_REASON =
+	'⛔ lane split park: this session is a dispatched lane child that promoted its own Issue to an epic ' +
+	'this run, and a split is not a park — do not apply `needs-decision` to the promoted epic and do not ' +
+	'send a `confirmation` Telegram. The parent reads an open Issue carrying `epic` as a split and ' +
+	'continues through its children; a question here has nobody to answer it (joshuafolkken/kit#3296, ' +
+	'measured 2026-10-06 when the child for #3255 parked its promoted epic). If what remains of the ' +
+	'original work needs a person, park that child issue instead, then end the turn. The procedure is ' +
+	'`.claude/skills/workflow-commands/backlogrun-park.md` → "Splitting a child mid-run". This rule fires ' +
+	'on every occurrence, not once per run.'
+
+// It declares no `keeps`: not parking is the absence of a call, so the row is reported unmeasured
+// rather than scored on an act that does not exist (`lane-carry-conflict.ts`).
+const ROW = {
+	id: 'lane-split-park',
+	is_trigger: bash_triggers.on_bash_command(is_candidate),
+	reason: LANE_SPLIT_PARK_REASON,
+	decide,
+}
+
+const lane_split_park = {
+	LANE_SPLIT_PARK_REASON,
+	ROW,
+	promoted_issues,
+}
+
+export { lane_split_park }

package/scripts/rules/oracle-firing.ts

@@ -133,7 +133,7 @@ function firing_oracles(): ReadonlyArray<{
 	return decision_oracle.DECISION_ORACLES.flatMap((oracle) => {
 		const firing_point = FIRING.get(oracle.name)
 
-		return firing_point === undefined ? [] : [{ oracle, firing_point }]
+		return firing_point === undefined ? [] : { oracle, firing_point }
 	})
 }
 

package/scripts/rules/poll-loop.ts

@@ -17,7 +17,7 @@ import { bash_triggers } from './bash-triggers'
 // way the command's *exit* is not what ends the wait, and each pass spends a full-context round trip.
 // A command backgrounded with `run_in_background` re-invokes the run when it exits — the completion
 // notification is what ends the wait on the task itself, which is the mechanism this row hands back,
-// the same reading joshuafolkken/kit#1510 took for the foreground push (`run-tail.ts`).
+// the same reading joshuafolkken/kit#1510 took for the foreground push (`run-tail-rule.ts`).
 //
 // **It fires on every occurrence**, for the reason `git-force.ts` does: a poll loop wastes the same
 // round trips each time it is armed, so refused-once-and-free-after would put every loop but the first

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

@@ -2,7 +2,7 @@ import { cost_cli, type CostVerdict } from '#scripts/cost-runtime/cost-cli'
 import { cost_verdict } from '#scripts/cost-runtime/cost-verdict'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
 import { lane_paths } from '#scripts/lane/lane-paths'
-import { run_cut, type RunCut } from '#scripts/run/run-cut'
+import { run_cut, type RunCut } from '#scripts/run/cut/run-cut'
 import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
 import { bash_triggers } from './bash-triggers'
 import { shell_segments } from './shell-segments'
@@ -100,7 +100,7 @@ interface LaneCutState {
 	directory: string
 	carried: (now?: Date) => RunCut | undefined
 	marked_issue: string | undefined
-	// **The recent-window context verdict, read lazily** (joshuafolkken/kit#2312). It is a thunk, like
+	// **The context verdict, read lazily** (joshuafolkken/kit#2312). It is a thunk, like
 	// `carried`, so `current_state` builds the object without pricing a session — the read happens only
 	// after the command and lane checks pass, off the handful of calls that actually run a lane's gate.
 	context_verdict: () => CostVerdict
@@ -136,7 +136,7 @@ function uncut_lane_issue(state: LaneCutState): string | undefined {
 	return state.carried()?.issue === issue ? undefined : issue
 }
 
-// **The cut is taken only when the recent-window context is worth its resume** (joshuafolkken/kit#2312).
+// **The cut is taken only when the current context is worth its resume** (joshuafolkken/kit#2312).
 // Below the shared `CONTEXT_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 joshuafolkken/kit#1933 relies on. The verdict is

package/scripts/rules/protected-files.ts

@@ -2,12 +2,15 @@ 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 { bash_triggers } from './bash-triggers'
+import { shell_segments } from './shell-segments'
 
 // The trigger and the delivered text behind the `protected-file` row of `delivered-rules.ts`
 // (joshuafolkken/kit#2983): the two files a run's own file tools must not touch.
 //
-// - **`.env` is never read.** It carries the Telegram bot token, and a Read lands it in the transcript.
-//   The scripts that need it load it in their own process, so refusing the tool costs them nothing.
+// - **`.env` is never read** — by the `Read` tool or by a shell reader in a `Bash` call. It carries the
+//   Telegram bot token, and either read lands it in the transcript. The scripts that need it load it
+//   in their own process, so refusing the call costs them nothing.
 // - **`.claude/settings.json` is never edited in a consumer repository.** It is the deny list and the
 //   hooks that enforce every other rule, so a run that rewrites it can switch the guards off; `josh
 //   sync` owns it there. Only a kit consumer's file is refused — decided per file from the repository
@@ -20,6 +23,29 @@ const READ_TOOL = 'Read'
 const EDIT_TOOLS: ReadonlySet<string> = new Set(['Edit', 'Write'])
 const ENVIRONMENT_FILE = '.env'
 const SETTINGS_FILE = path.join('.claude', 'settings.json')
+const WHITESPACE = /\s+/u
+const TOKEN_QUOTES = /["']/gu
+const INPUT_REDIRECT = '<'
+const SHELL_READERS: ReadonlySet<string> = new Set([
+	'.',
+	'awk',
+	'bat',
+	'cat',
+	'cut',
+	'grep',
+	'head',
+	'less',
+	'more',
+	'nl',
+	'od',
+	'rg',
+	'sed',
+	'sort',
+	'source',
+	'strings',
+	'tail',
+	'xxd',
+])
 
 function file_path_of(call: GuardedCall): string {
 	if (!json_value.is_record(call.input)) return ''
@@ -29,8 +55,36 @@ function file_path_of(call: GuardedCall): string {
 	return typeof value === 'string' ? value : ''
 }
 
+function is_environment_path(token: string): boolean {
+	return path.basename(token.replaceAll(TOKEN_QUOTES, '')) === ENVIRONMENT_FILE
+}
+
+// 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. `.env.example` and
+// `.env.local` keep passing: only a token whose basename is exactly `.env` counts.
+function is_environment_read_segment(segment: string): boolean {
+	const words = segment
+		.replaceAll(INPUT_REDIRECT, ' < ')
+		.split(WHITESPACE)
+		.filter((word) => word !== '')
+	const is_redirected = words.some(
+		(word, index) => word === INPUT_REDIRECT && is_environment_path(words[index + 1] ?? ''),
+	)
+	const [command = '', ...rest] = words
+
+	return (
+		is_redirected || (SHELL_READERS.has(command) && rest.some((word) => is_environment_path(word)))
+	)
+}
+
+function is_environment_shell_read(command: string): boolean {
+	return shell_segments.segments_of(command).some((segment) => is_environment_read_segment(segment))
+}
+
 function is_environment_read(call: GuardedCall): boolean {
-	return call.name === READ_TOOL && path.basename(file_path_of(call)) === ENVIRONMENT_FILE
+	if (call.name === READ_TOOL) return is_environment_path(file_path_of(call))
+
+	return bash_triggers.on_bash_command(is_environment_shell_read)(call)
 }
 
 // The repository the settings file belongs to is two levels above it (`<root>/.claude/settings.json`).
@@ -55,7 +109,8 @@ function is_protected_file_call(
 }
 
 const PROTECTED_FILE_REASON =
-	'⛔ protected file: `.env` holds the Telegram bot token, so reading it puts a secret in the ' +
+	'⛔ protected file: `.env` holds the Telegram bot token, so reading it — with the Read tool or a ' +
+	'shell reader such as `cat` / `grep` / `source` — puts a secret in the ' +
 	'transcript — the scripts that need it load it in their own process. `.claude/settings.json` in a ' +
 	'consumer repository is the deny list and the hooks every other rule rests on, so a run must not ' +
 	'rewrite it; `josh sync` owns it, and a change belongs upstream in kit (`CLAUDE.md` → "Route ' +

package/scripts/rules/{run-tail.ts → run-tail-rule.ts}

@@ -166,7 +166,7 @@ const RUN_TAIL_REASON =
 	'run**, so ' +
 	'reissuing the same call in the foreground will be refused again.'
 
-const run_tail = {
+const run_tail_rule = {
 	RUN_TAIL_REASON,
 	decide,
 	is_backgrounded_push_step,
@@ -175,4 +175,4 @@ const run_tail = {
 	is_push_step_call,
 }
 
-export { run_tail }
+export { run_tail_rule }

package/scripts/rules/shell-body-trigger.ts

@@ -140,7 +140,7 @@ const BODY_FLAG = new RegExp(
 	'u',
 )
 
-// **A flag is only a flag outside the quotes**, the same reading `run-tail.ts` takes of a pull-request
+// **A flag is only a flag outside the quotes**, the same reading `run-tail-rule.ts` takes of a pull-request
 // title. This repository's own refusal text names `--body-file <path>`, so a `grep` or an `echo`
 // quoting it would otherwise be scored as a run that passed a body by path. The quoted spellings of
 // the same thing are not lost by blanking: `--field "body=@<path>"` is a whole-value file reference,

package/scripts/rules/stop-rules.ts

@@ -83,6 +83,9 @@ interface StopContext {
 	handed_off: boolean
 	// The resolved `JOSH_SESSION_LANG` — `session_language.resolve_session_lang` (joshuafolkken/kit#2470).
 	session_lang: string
+	// This session is an agent kit launched under `claude -p` — `agent_headless.is_headless`
+	// (joshuafolkken/kit#3245). No person reads its reply, so the rules on how a reply is written stand down.
+	headless_agent: boolean
 }
 
 interface StopOutcome {
@@ -170,12 +173,10 @@ const HEADLESS_WAIT_CALLS = ['"command":"pnpm josh lane:await']
 const HEADLESS_WAIT_BODY =
 	' this is a `claude -p` `backlogrun` parent (`JOSH_RUN_HEADLESS`) with lanes still ' +
 	'in flight, and ending this turn ends the process — its background waits are killed with it and the ' +
-	'lanes are left without a parent. Wait in the foreground instead: run `pnpm josh lane:await <N...>` ' +
-	'for the in-flight lanes as a foreground command within the tool timeout (with ' +
-	'`pnpm josh run:progress --wait` in the background for the heartbeat, which streams its reports ' +
-	'itself and lives while this turn does), act on what it reports, and continue the loop. End the turn only ' +
-	'after `pnpm josh run:carry --cut` or `--end` (`backlogrun-progress.md` → "The parent keeps no clock ' +
-	'of its own").'
+	"lanes are left without a parent. Do not watch them yourself: the `run:wake` supervisor's driver " +
+	'watches the lanes and wakes a session only for a branch that needs judging. Hand the loop back with ' +
+	'`pnpm josh run:carry --cut --owner "$PPID"` (or `--end` when the run is over), then end the turn ' +
+	'(`backlogrun-progress.md` → "Picking the lanes up in the fresh session").'
 
 const HEADLESS_WAIT_REASON = `${HEADLESS_WAIT_MARKER}${HEADLESS_WAIT_BODY}`
 
@@ -263,13 +264,23 @@ function citation_reason(context: StopContext): string | undefined {
 	return build_citation_reason(references)
 }
 
+// The two rules on how a reply is written. **A headless agent's reply has no reader**
+// (joshuafolkken/kit#3245): its text lands in a stream-json log, so correcting its citations or its
+// language costs a turn and reaches nobody. The artifacts a person does read — a Telegram, an Issue, a
+// pull request — are held to the same rules by their own guards, not here.
+function wording_reason(context: StopContext): string | undefined {
+	if (context.headless_agent) return undefined
+
+	return citation_reason(context) ?? language_reason(context)
+}
+
 // The three rules that read the reply itself, filing offer first and the language last. A drifted reply
 // refused for another reason is not rewritten, but the drift still ends: `block_envelope` appends the
 // session-language note to every refusal, so the turn it continues is written in the session language.
 function reply_reason(context: StopContext): string | undefined {
 	if (needs_filing(context)) return FILING_OFFER_REASON
 
-	return citation_reason(context) ?? language_reason(context)
+	return wording_reason(context)
 }
 
 // The headless wait holds past the loop-breaker until the spin bound is reached.

package/scripts/rules/test-declared-commit.ts

@@ -1,9 +1,9 @@
 import { test_declared_changed } from '#scripts/test/test-declared-changed'
 import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
-import { run_tail } from './run-tail'
+import { run_tail_rule } from './run-tail-rule'
 
 // The trigger and the delivered text behind the `test-declared` row of `delivered-rules.ts`
-// (joshuafolkken/kit#2118). It lives beside `run-tail.ts` and the other per-rule modules rather than
+// (joshuafolkken/kit#2118). It lives beside `run-tail-rule.ts` and the other per-rule modules rather than
 // inline in the enumeration, so the enumeration stays a list of rows.
 //
 // **A commit whose code change carries no test, refused at the commit stage `run-tail` already
@@ -11,7 +11,7 @@ import { run_tail } from './run-tail'
 // the input is mechanical — the changed paths, the test-file spelling, the exempt-path enumeration —
 // so it is a delivered rule rather than resident prose.
 //
-// **No new delivery path.** The command half is `run_tail.is_push_step_call`, reused verbatim, and the
+// **No new delivery path.** The command half is `run_tail_rule.is_push_step_call`, reused verbatim, and the
 // only thing added is the world-read: the working-tree verdict `pnpm josh test:declared` prints. Like
 // `pre-gate-cut`, the command test comes first and the git read second, so an ordinary `Bash` call
 // pays nothing and only a `pnpm josh git -y` spawns `git status`.
@@ -23,7 +23,7 @@ import { run_tail } from './run-tail'
 // commit; refusing once and passing the reissue is the same safe direction `issue-comments` takes, and
 // a compliant reissue that adds a test flips the verdict to `satisfied` and stops matching anyway.
 function is_untested_commit(call: GuardedCall): boolean {
-	if (!run_tail.is_push_step_call(call)) return false
+	if (!run_tail_rule.is_push_step_call(call)) return false
 
 	return test_declared_changed.current_verdict() === 'required'
 }