@joshuafolkken/kit 1.1178.0 → 1.1240.0

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'

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'
 }

package/scripts/rules/wip-cap.ts

@@ -0,0 +1,63 @@
+import { bash_triggers } from './bash-triggers'
+import { shell_segments } from './shell-segments'
+
+// The trigger and the delivered text behind the `wip-cap` row of `delivered-rules.ts`, moved out of
+// the enumeration so the list stays a list (joshuafolkken/kit#3264).
+
+// The whole of the WIP cap, in the shape a refusal can carry: the count, the refusal, the two
+// exemptions and the three tests that decide the second one. The three tests are spelled out rather
+// than named, because a delivery that said only "an interrupt is exempt" would hand the deciding back
+// to judgement at exactly the moment nothing else is open to read (joshuafolkken/kit#1518).
+// `WIP_CAP` is the number's single source; `wip-cap.md` states it once and a test pins the two equal.
+const WIP_CAP = 30
+const WIP_CAP_REASON =
+	`⛔ backlog WIP cap: \`pnpm josh issue:file\` counts the target repository's open Issues before filing. With more than ${String(WIP_CAP)} ` +
+	'open, close one first; nothing honestly closable means do not file — the command holds such a filing. ' +
+	'Two filings are exempt and proceed while stating the overage — one the run is blocked by (`--over-cap`, ' +
+	'or the `tier-a` / `split` route), and an interrupt (`--route interrupt`), decided by three tests rather ' +
+	'than judgement: a verification answers wrongly, a documented workflow cannot complete, or data is lost ' +
+	'or written outside the repository. Meeting none of the three, the finding is discretionary and waits. ' +
+	'Both procedures are in `prompts/collaboration-workflow/wip-cap.md`. Reissue this call and let the ' +
+	'command count — it fires once per run and cannot repeat on the call in hand.'
+
+// **Keeping the WIP cap is counting the open Issues**, which is the one act the rule asks for before
+// a filing.
+//
+// **It has to be Issues, open, and a listing — all three, in one segment.** A pattern that took any
+// of them alone scored `gh pr list --state open` and `epic:bundle`'s candidate search as the count,
+// and those inflate exactly the ratio the retirement decision reads. `gh issue list` alone is not
+// enough either: the cap is about *open* Issues, and a listing that does not say so is some other
+// question. Segment-wise like the comments predicate, so a spelling quoted inside a filing's body
+// is not read as the count that filing skipped.
+const ISSUE_LISTING = /^gh\s+(?:-{1,2}[\w-]+(?:[= ]\S+)?\s+)*issue\s+list\b/u
+const ISSUES_QUERY = /repos\/[^\s'"]*\/issues\?[^\s'"]*state=open/u
+const OPEN_STATE = /--state[= ]open|state=open/u
+// **A label filter makes it a different question.** `gh issue list --label epic --state open` and
+// `…/issues?labels=epic&state=open` ask which epics are open, which is what `epic:bundle` and the
+// Issue template do; counting either as the WIP count would credit the cap as kept by a run that
+// never counted the backlog. The residual the pattern cannot separate is named in
+// `docs/josh-commands.md`: the inventory command in the `diag` skill is byte-identical to a hand count
+// of the backlog, so no pattern can tell those two apart.
+const LABEL_FILTER = /--label\b|[?&]labels=/u
+
+function counts_open_issues(command: string): boolean {
+	return shell_segments.segments_of(command).some((segment) => {
+		if (LABEL_FILTER.test(segment)) return false
+
+		return (ISSUE_LISTING.test(segment) && OPEN_STATE.test(segment)) || ISSUES_QUERY.test(segment)
+	})
+}
+
+// The enumeration row itself, so `delivered-rules.ts` spreads one entry rather than restating the
+// trigger and reason it already single-sources here. Once per run: the refusal changes what the run
+// knows, so the reissue is let through.
+const ROW = {
+	id: 'wip-cap',
+	is_trigger: bash_triggers.on_bash_command(bash_triggers.is_issue_filing),
+	reason: WIP_CAP_REASON,
+	keeps: bash_triggers.on_bash_command(counts_open_issues),
+}
+
+const wip_cap = { ROW, WIP_CAP, WIP_CAP_REASON }
+
+export { wip_cap }

package/scripts/run/{run-carry-args.ts → carry/run-carry-args.ts}

@@ -1,6 +1,6 @@
 import { cli_flags } from '#scripts/lib/cli-flags'
+import { run_issue_number } from '#scripts/run/run-issue-number'
 import { run_carry, type CarryChange, type CarryClaimRequest, type CarryOwner } from './run-carry'
-import { run_issue_number } from './run-issue-number'
 
 // The argument half of `josh run:carry`. It sat inside `run-carry-cli.ts` until the ownership answers
 // joshuafolkken/kit#1722 added took that file to 96% of the 300-line limit, and the seam it split on
@@ -9,6 +9,7 @@ import { run_issue_number } from './run-issue-number'
 
 const NO_INCREMENT = 0
 const ONE_CUT = 1
+const ONE_MERGE = 1
 // The four request groups below are mutually exclusive, so more than one of them named in a single
 // invocation is a usage error rather than an order to guess.
 const ONE_GROUP = 1
@@ -22,7 +23,7 @@ const MIN_PID = 1
 // cannot advance a budget that is no longer its own. `--end` alone accepts it and ignores it, and a
 // usage line that offered it there would be promising an ownership check nothing performs.
 const USAGE =
-	'Usage: josh run:carry [--json] | --begin <invocation> [--owner <pid>] | --resume <invocation> [--owner <pid>] | (--cut | --merged <count> | --filed <count> | --done <issue> | --retrospective --summary <text>) [--owner <pid>] | --end [--stopped <reason>]'
+	'Usage: josh run:carry [--json] | --begin <invocation> [--owner <pid>] | --resume <invocation> [--owner <pid>] | (--cut | --merged <issue> | --filed <count> | --done <issue> | --retrospective --summary <text>) [--owner <pid>] | --end [--stopped <reason>]'
 
 const OPTIONS = {
 	begin: { type: 'string' },
@@ -89,12 +90,12 @@ function to_count(value: OptionValue): number | undefined {
 	return COUNT_PATTERN.test(text) ? Number(text) : undefined
 }
 
-// **`--done` names an issue, so it is checked as one and not as a count.** The shape is
-// `run-issue-number.ts`'s, which already refuses `0` and a leading zero — the same rule the `run:*`
+// **`--done` and `--merged` name an issue, so each is checked as one and not as a count.** The shape
+// is `run-issue-number.ts`'s, which already refuses `0` and a leading zero — the same rule the `run:*`
 // commands interpolate a number under, imported rather than restated. Absent is an empty object rather
 // than a zero: there is no issue to record, which is a different fact from recording issue zero. A
-// present-but-malformed value invalidates the whole invocation, exactly as a bad `--merged` does.
-function to_done(value: OptionValue): Pick<CarryChange, 'done'> | undefined {
+// present-but-malformed value is `undefined`, which invalidates the whole invocation.
+function to_issue(value: OptionValue): { issue?: number } | undefined {
 	const text = cli_flags.string_of(value)
 
 	if (text === undefined) return {}
@@ -106,7 +107,30 @@ function to_done(value: OptionValue): Pick<CarryChange, 'done'> | undefined {
 	// The pattern is anchored on digits and bounds nothing, so the magnitude check is separate — the
 	// same shape `backlog_budget_cli.to_count` ends with. A number past the safe range would be
 	// recorded as a different number and never match anything in `remaining`.
-	return Number.isSafeInteger(issue) ? { done: issue } : undefined
+	return Number.isSafeInteger(issue) ? { issue } : undefined
+}
+
+function to_done(value: OptionValue): Pick<CarryChange, 'done'> | undefined {
+	const parsed = to_issue(value)
+
+	if (parsed === undefined) return undefined
+
+	return parsed.issue === undefined ? {} : { done: parsed.issue }
+}
+
+// **`--merged` names the issue that merged, never a count** (joshuafolkken/kit#3296). A bare count
+// could not be matched against `merged_issues`, so a parent that counted a merge by hand and the
+// driver's `run:merge` for the same issue added two for one merge. Naming the issue makes the hand
+// count the same change `run:merge` applies — one merge plus its number — so `apply_change`'s
+// duplicate check holds whichever of the two arrives first.
+function to_merged(value: OptionValue): Pick<CarryChange, 'merged' | 'merged_issue'> | undefined {
+	const parsed = to_issue(value)
+
+	if (parsed === undefined) return undefined
+
+	return parsed.issue === undefined
+		? { merged: NO_INCREMENT }
+		: { merged: ONE_MERGE, merged_issue: parsed.issue }
 }
 
 // The two boolean marks in the counting group — `--cut` and `--retrospective` — as the partial the
@@ -119,18 +143,18 @@ function to_marks(values: ParsedValues): Pick<CarryChange, 'cuts' | 'retrospecti
 }
 
 function to_change(values: ParsedValues): CarryChange | undefined {
-	const merged = to_count(values.merged)
+	const merged = to_merged(values.merged)
 	const filed = to_count(values.filed)
 	const done = to_done(values.done)
 
 	if (merged === undefined || filed === undefined || done === undefined) return undefined
 
-	return { merged, filed, ...to_marks(values), ...done }
+	return { ...merged, filed, ...to_marks(values), ...done }
 }
 
-// **A counting flag is what makes a count, never the sum of one.** `--merged 0` is a run reporting
-// that a wave merged nothing, and reading it as a bare read would answer `none` with exit 0 against
-// a record that is not there — the silent zero `docs/josh-commands.md` says exits 1.
+// **A counting flag is what makes a count, never the sum of one.** `--filed 0` is a run reporting
+// that it filed nothing, and reading it as a bare read would answer `none` with exit 0 against a
+// record that is not there — the silent zero `docs/josh-commands.md` says exits 1.
 function has_count(values: ParsedValues): boolean {
 	return (
 		values.cut === true ||
@@ -189,7 +213,7 @@ function is_summary_paired(values: ParsedValues): boolean {
 
 // The counting group, split out so the shape below stays a flat list of exits. The summary rides along
 // only when it is there — guaranteed paired with `--retrospective` by `is_summary_paired` — so a plain
-// `--merged` count never carries one.
+// `--merged` never carries one.
 function to_count_request(values: ParsedValues, owner: CarryOwner): Request | undefined {
 	const change = to_change(values)
 

package/scripts/run/{run-carry-change.ts → carry/run-carry-change.ts}

@@ -18,7 +18,9 @@ function next_merged_issues(
 ): ReadonlyArray<number> | undefined {
 	if (issue === undefined) return carry.merged_issues
 
-	return [...(carry.merged_issues ?? []), issue]
+	const current = carry.merged_issues ?? []
+
+	return current.includes(issue) ? current : [...current, issue]
 }
 
 function is_duplicate_merge(carry: RunCarry, change: CarryChange): boolean {
@@ -27,6 +29,24 @@ function is_duplicate_merge(carry: RunCarry, change: CarryChange): boolean {
 	return issue !== undefined && carry.merged_issues?.includes(issue) === true
 }
 
+// Whether a change carries anything besides its merge — a filing, a cut, a streak step, a done issue
+// or the retrospective mark.
+function has_other_change(change: CarryChange): boolean {
+	const amounts = [change.filed, change.cuts, change.failures, change.outages]
+	const has_amount = amounts.some((amount) => (amount ?? NO_INCREMENT) > NO_INCREMENT)
+
+	return has_amount || change.done !== undefined || change.retrospective === true
+}
+
+// **A duplicate merge drops only the merge** (joshuafolkken/kit#3296): `--merged <issue>` may ride
+// beside `--filed` or `--done` in one call, and those are still increments the record has not seen.
+// Only a duplicate carrying nothing else leaves the record untouched, which is `undefined` here.
+function effective_change(carry: RunCarry, change: CarryChange): CarryChange | undefined {
+	if (!is_duplicate_merge(carry, change)) return change
+
+	return has_other_change(change) ? { ...change, merged: NO_INCREMENT } : undefined
+}
+
 function next_counts(
 	carry: RunCarry,
 	change: CarryChange,
@@ -47,18 +67,20 @@ function apply_change(
 	change: CarryChange,
 	now: Date = new Date(),
 ): RunCarry {
-	if (is_duplicate_merge(carry, change)) return carry
+	const effective = effective_change(carry, change)
+
+	if (effective === undefined) return carry
 
-	const streak = run_carry_streak.next_state(carry, change, now)
+	const streak = run_carry_streak.next_state(carry, effective, now)
 	const next: RunCarry = {
 		...carry,
-		...next_counts(carry, change),
-		merged_issues: next_merged_issues(carry, change.merged_issue),
+		...next_counts(carry, effective),
+		merged_issues: next_merged_issues(carry, effective.merged_issue),
 		failures: streak.failures,
 		outages: streak.outages,
 		last_outage_at: streak.last_outage_at,
-		done: next_done(carry, change.done),
-		retrospective: change.retrospective === true || carry.retrospective,
+		done: next_done(carry, effective.done),
+		retrospective: effective.retrospective === true || carry.retrospective,
 	}
 
 	stamp_file.write_stamp(target, next)

package/scripts/run/{run-carry-cli.ts → carry/run-carry-cli.ts}

@@ -2,6 +2,9 @@
 import { fileURLToPath } from 'node:url'
 import { cost_cli } from '#scripts/cost-runtime/cost-cli'
 import { cost_verdict } from '#scripts/cost-runtime/cost-verdict'
+import { run_event_stream } from '#scripts/run/event/run-event-stream'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
+import { run_stop_notify } from '#scripts/run/run-stop-notify'
 import {
 	run_carry,
 	type CarryClaim,
@@ -12,9 +15,6 @@ import {
 import { run_carry_args, type CountRequest, type Request } from './run-carry-args'
 import { run_carry_conversation } from './run-carry-conversation'
 import { run_carry_stash } from './run-carry-stash'
-import { run_event_stream } from './run-event-stream'
-import { run_event_stream_emit } from './run-event-stream-emit'
-import { run_stop_notify } from './run-stop-notify'
 
 // `josh run:carry` — the record that carries one invocation's budget across its own session cuts
 // (joshuafolkken/kit#1714). A `backlogrun` begins it, counts a merge and a filing into it, marks each
@@ -303,9 +303,7 @@ function blocked_count(
 	request: CountRequest,
 	is_json: boolean,
 ): number | undefined {
-	if (run_carry.is_count_refused(carry, request.owner)) {
-		return report_count_refused(carry, is_json)
-	}
+	if (run_carry.is_count_refused(carry, request.owner)) return report_count_refused(carry, is_json)
 
 	if (is_cut_count(request) && run_carry.is_at_cut_cap(carry)) {
 		return report_cut_capped(carry, is_json)

package/scripts/run/{run-carry.ts → carry/run-carry.ts}

@@ -2,10 +2,10 @@ import { backlog_budget } from '#scripts/backlog/backlog-budget'
 import { git_command } from '#scripts/git/git-command'
 import { process_identity } from '#scripts/josh/process-identity'
 import { stamp_file } from '#scripts/josh/stamp-file'
+import { run_invocation } from '#scripts/run/run-invocation'
 import { z } from 'zod'
 import { run_carry_change } from './run-carry-change'
 import { run_carry_conversation } from './run-carry-conversation'
-import { run_invocation } from './run-invocation'
 
 // joshuafolkken/kit#1714: a `backlogrun` declares a budget — `--max`, `--idle` and the 8-hour
 // whole-run bound — and then loses all of it at the session cut, because the cut ends the session and