@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/rules/lane-background.ts

@@ -26,7 +26,7 @@ import { run_tail_rule } from './run-tail-rule'
 // killed at the turn's end before any supervisor exists. Issued in the foreground it returns at
 // `launched` within the tool timeout, and the supervisor carries the rest. A backgrounded `ship` alone
 // is not refused but rewritten into that foreground call (`foreground_input`); one chained after
-// another long command is refused.
+// another long command is refused. A foreground `ship` without the cap is given it the same way.
 //
 // **Its stop-time half reads the same fact from the other side.** A backgrounded task the transcript
 // launched but never saw finish is still running, and in a child the stop about to happen kills it —
@@ -35,17 +35,23 @@ import { run_tail_rule } from './run-tail-rule'
 
 // The josh subcommands that run long enough to be backgrounded, as `time_shell` names them — canonical,
 // so the `ga` / `g` / `fu` aliases are covered by the one spelling.
-const SHIP_COMMAND = `${time_shell.JOSH_PREFIX}ship`
+// `ship`, `ship:wait` and `lane:plan` are run in the foreground at the cap rather than refused: a
+// `ship:wait` left at the two-minute default is moved aside mid-chunk and dies with the turn, its verdict
+// unread, and a cut `lane:plan` leaves its plan recorded with the check it gates unanswered.
+const FOREGROUND_COMMANDS: ReadonlySet<string> = new Set(
+	['ship', 'ship:wait', 'lane:plan'].map((name) => `${time_shell.JOSH_PREFIX}${name}`),
+)
 const LONG_RUNNING_COMMANDS: ReadonlySet<string> = new Set([
 	...['gate', 'git', 'followup'].map((name) => `${time_shell.JOSH_PREFIX}${name}`),
-	SHIP_COMMAND,
+	...FOREGROUND_COMMANDS,
 ])
 
 const BACKGROUND_KEY = 'run_in_background'
 const TIMEOUT_KEY = 'timeout'
-// The longest a foreground Bash call may run. A backgrounded call rarely carries a `timeout`, and one that
-// does may exceed the foreground cap, so the rewrite sets it: left at the two-minute default, a preflight
-// whose scoped pair outruns it is cut before `launched`, the #3027 failure the rewrite exists to avoid.
+// The longest a foreground Bash call may run. A `ship` rarely carries a `timeout`, and a backgrounded one
+// that does may exceed the foreground cap, so the rewrite sets it: left at the two-minute default, a
+// preflight whose scoped pair outruns it is cut before `launched` (#3027) or moved to the background and
+// killed with the turn (#4101).
 const FOREGROUND_TIMEOUT_MS = 600_000
 
 function is_backgrounded(input: unknown): boolean {
@@ -56,13 +62,13 @@ function long_commands_of(command: string): Array<string> {
 	return time_shell.josh_commands_of(command).filter((name) => LONG_RUNNING_COMMANDS.has(name))
 }
 
-// A call whose long-running work is `ship` alone. In a child a foreground `ship` already detaches
-// itself after its preflight (`run-ship-cli.ts` → `should_detach`), so the only fault in backgrounding
-// it is the flag — and the flag is what the hook rewrites.
+// A call whose long-running work is `ship` or `ship:wait` alone. In a child a foreground `ship` already
+// detaches itself after its preflight (`run-ship-cli.ts` → `should_detach`), so the only fault in
+// backgrounding it is the flag — and the flag is what the hook rewrites.
 function ships_alone(command: string): boolean {
 	const names = long_commands_of(command)
 
-	return names.length > 0 && names.every((name) => name === SHIP_COMMAND)
+	return names.length > 0 && names.every((name) => FOREGROUND_COMMANDS.has(name))
 }
 
 function backgrounded_bash_command(call: GuardedCall): string | undefined {
@@ -101,38 +107,72 @@ function is_background_long_run(
 	return is_candidate(call) && is_lane_child()
 }
 
-// **A backgrounded `ship` in a child is rewritten, not refused**. The refusal
-// asked for nothing but the same call in the foreground — 14 of 41 lane `ship` refusals in one measured
-// backlogrun were that round trip, paid at the run's largest context. The input with the flag cleared,
-// or `undefined` for every call this does not apply to.
+// The input of a Bash call whose long-running work is `ship` alone, or `undefined` for any other call.
+function ship_alone_input(call: GuardedCall): Record<string, unknown> | undefined {
+	if (call.name !== cost_blocks.BASH_TOOL || !json_value.is_record(call.input)) return undefined
+
+	return ships_alone(time_shell.bash_command(call.input)) ? call.input : undefined
+}
+
+// A foreground call that already carries the foreground cap, which the harness never moves aside.
+function is_capped_foreground(input: Record<string, unknown>): boolean {
+	const timeout = input[TIMEOUT_KEY]
+
+	return !is_backgrounded(input) && typeof timeout === 'number' && timeout >= FOREGROUND_TIMEOUT_MS
+}
+
+// **A `ship` in a child is run in the foreground at the cap, not refused**. The refusal of a
+// backgrounded one asked for nothing but the same call in the foreground — 14 of 41 lane `ship`
+// refusals in one measured backlogrun were that round trip, paid at the run's largest context.
+//
+// A foreground one at the two-minute default is moved aside once its preflight outruns it, and dies
+// the same way (joshuafolkken/kit#4101). The input with the flag cleared and the cap set, or
+// `undefined` for every call this does not apply to.
 function foreground_input(
 	call: GuardedCall,
 	is_lane_child: () => boolean = () => lane_child_marker.is_child_of(process.cwd()),
 ): Record<string, unknown> | undefined {
-	if (!is_backgrounded_ship(call) || !json_value.is_record(call.input) || !is_lane_child()) {
-		return undefined
-	}
+	const input = ship_alone_input(call)
+
+	if (input === undefined || is_capped_foreground(input) || !is_lane_child()) return undefined
 
-	return { ...call.input, [BACKGROUND_KEY]: false, [TIMEOUT_KEY]: FOREGROUND_TIMEOUT_MS }
+	return { ...input, [BACKGROUND_KEY]: false, [TIMEOUT_KEY]: FOREGROUND_TIMEOUT_MS }
 }
 
 const FOREGROUND_NOTE =
-	'lane background: this lane child backgrounded `josh ship`, which would die with the headless turn ' +
-	'before its supervisor exists — so it was run in the foreground instead, where it detaches itself ' +
-	'after the preflight. End the turn on `launched` / `busy`.'
+	"lane background: a lane child's `josh ship`, `josh ship:wait` or `josh lane:plan` backgrounded, by its flag or by " +
+	'outrunning the Bash timeout, dies with the headless turn — so it was run in the foreground at the ' +
+	'600000 ms cap, where `ship` detaches itself after the preflight. Then follow ' +
+	'`chain-rule.md` step 0 (`josh ship:wait` on `launched`).'
+
+type LaunchedIds = (block: TranscriptBlock) => ReadonlyArray<string>
+
+// One line's word on each id: a launch opens it, a finish notice closes it.
+function apply_line(open: Set<string>, line: string, launched_ids: LaunchedIds): void {
+	const parsed = time_transcript_line.parse_line(line)
+
+	if (parsed === undefined) return
+
+	const launched = parsed.blocks.flatMap((block) => launched_ids(block))
+
+	for (const id of launched) open.add(id)
+	open.delete(parsed.finished_background)
+}
 
 // The launches `launched_ids` reads off the transcript tail that never saw their finish. A launch is
-// read off its own tool result and a finish off the harness notice, both by `time_transcript_line`.
-function unfinished_ids(
-	tail: string,
-	launched_ids: (block: TranscriptBlock) => ReadonlyArray<string>,
-): ReadonlyArray<string> {
-	const lines = tail.split('\n').map((line) => time_transcript_line.parse_line(line))
-	const finished = new Set(lines.map((line) => line?.finished_background ?? ''))
-	const blocks = lines.flatMap((line) => line?.blocks ?? [])
-	const launched = blocks.flatMap((block) => launched_ids(block))
+// read off its own tool result and a finish off the harness notice or a `TaskStop` result, both by
+// `time_transcript_line`.
+//
+// **Read in order, so the later word on an id wins.** A subagent resumed by `SendMessage` runs again
+// under the id its first run's notice already named; a set of every finish ever seen would read the
+// resumed run as finished (joshuafolkken/kit#4347).
+function unfinished_ids(tail: string, launched_ids: LaunchedIds): ReadonlyArray<string> {
+	const open = new Set<string>()
 
-	return launched.filter((id) => id !== '' && !finished.has(id))
+	for (const line of tail.split('\n')) apply_line(open, line, launched_ids)
+	open.delete('')
+
+	return [...open]
 }
 
 // The background tasks the tail launched and never saw finish — commands and subagents alike,
@@ -147,11 +187,17 @@ function pending_agent_ids(tail: string): ReadonlyArray<string> {
 	return unfinished_ids(tail, (block) => [block.agent_id])
 }
 
+// The backgrounded commands alone — what tells a stop with only subagents left apart from one a
+// command still holds.
+function pending_command_ids(tail: string): ReadonlyArray<string> {
+	return unfinished_ids(tail, (block) => [block.background_id])
+}
+
 const LANE_BACKGROUND_REASON =
 	'⛔ lane background: this session is a dispatched lane child (`JOSH_LANE_CHILD`), a headless ' +
 	'process whose background tasks die when the turn ends. Hand over to ' +
-	'`pnpm josh ship --detach --review "<title> #<N>"`, issued in the foreground, then end the turn on ' +
-	'`launched` / `busy`. It fires on every occurrence ' +
+	'`pnpm josh ship --detach --review "<title> #<N>"`, issued in the foreground, then `josh ship:wait <N>` on ' +
+	'`launched` or end the turn. It fires on every occurrence ' +
 	'(`.claude/skills/workflow-commands/chain-rule.md` step 0).'
 
 const LANE_BACKGROUND_STOP_REASON =
@@ -159,6 +205,15 @@ const LANE_BACKGROUND_STOP_REASON =
 	'it launched has not finished, and ending this turn kills it. Wait for it in the foreground, or ' +
 	're-issue the work through `pnpm josh ship --detach` — do not notify, stop or repeat your reply.'
 
+// **Only subagents left: the wait that receives their answer** (joshuafolkken/kit#4803). Their completion
+// notice is delivered only when a tool call ends, so one long hand-written loop holds it back until the
+// loop itself gives up; short foreground calls, one at a time, let it in at the first one to end.
+const LANE_AGENT_STOP_REASON =
+	'⛔ lane agent stop: this is a dispatched lane child (`JOSH_LANE_CHILD`) and a subagent it launched ' +
+	'has not finished; ending this turn kills it. Its completion notice arrives only when a tool call ' +
+	'ends: wait with one short foreground call at a time (`sleep 20`) until it arrives — never a loop ' +
+	'over its `.output`. Do not notify, stop or repeat your reply.'
+
 // The row itself, so `delivered-rules.ts` spreads one entry. It fires on every occurrence (`decide`
 // returns true): a child must never background these, so the route is always the detached ship, never
 // a reissue. It declares no `keeps`: the detached ship is a different command, not this call made right.
@@ -167,10 +222,24 @@ const ROW = {
 	is_trigger: (call: GuardedCall): boolean => is_background_long_run(call),
 	reason: LANE_BACKGROUND_REASON,
 	decide: (): boolean => true,
+	// `pretool-guard.ts` rewrites a lone `josh ship` to the foreground rather than refusing it; this is
+	// the note it attaches, so `rule-value.ts` counts that rewrite as this row's delivery.
+	rewrite_note: FOREGROUND_NOTE,
+	// The Stop hook delivers the same rule at the turn's end, for the background task or subagent the
+	// turn would kill.
+	stop_reasons: [LANE_BACKGROUND_STOP_REASON, LANE_AGENT_STOP_REASON],
+	about: {
+		title: 'Lane child background push',
+		topic: '`.claude/skills/workflow-commands/background-commands.md`',
+		fires:
+			'a dispatched lane child backgrounding `josh gate` / `git` / `followup` / `ship`; it hands over `pnpm josh ship --detach`; the Stop hook also blocks ending a turn with its background task or subagent unfinished. Every occurrence',
+		quiet: 'not a lane child, or the foreground `ship --detach`',
+	},
 }
 
 const lane_background = {
 	FOREGROUND_NOTE,
+	LANE_AGENT_STOP_REASON,
 	LANE_BACKGROUND_REASON,
 	LANE_BACKGROUND_STOP_REASON,
 	ROW,
@@ -178,6 +247,7 @@ const lane_background = {
 	is_background_long_run,
 	pending_agent_ids,
 	pending_background_ids,
+	pending_command_ids,
 }
 
 export { lane_background }

package/scripts/rules/lane-carry-conflict.ts

@@ -109,6 +109,12 @@ const ROW = {
 	is_trigger: bash_triggers.on_bash_command(is_carry_conflict),
 	reason: LANE_CARRY_CONFLICT_REASON,
 	decide: (): boolean => true,
+	about: {
+		title: 'Lane child carry commands',
+		topic: '`.claude/skills/workflow-commands/backlogrun-lanes.md`',
+		fires: 'a dispatched lane child running `pnpm josh run:merge` / `run:carry`. Every occurrence',
+		quiet: 'not a lane child — the parent owns the run budget',
+	},
 }
 
 const lane_carry_conflict = {

package/scripts/rules/lane-direct-tool.ts

@@ -0,0 +1,172 @@
+import os from 'node:os'
+import { cost_blocks } from '#scripts/cost-runtime/cost-blocks'
+import { command_memory, type ToolCall } from '#scripts/gate/command-memory'
+import { core_weights } from '#scripts/gate/core-weights'
+import { lane_child_marker } from '#scripts/lane/lane-child-marker'
+import { json_value } from '#scripts/lib/json-value'
+import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
+import { time_shell } from '#scripts/time-runtime/time-shell'
+import { bash_triggers } from './bash-triggers'
+import { timed_rerun } from './timed-rerun'
+
+// A dispatched lane child is stopped from running a heavy tool directly. The core budget
+// (`scripts/gate/core-budget.ts`) counts only what a `josh` command reserves, so an `eslint`, `vitest`,
+// `cspell` or `tsc` a lane agent launches itself is neither refused nor counted: it overlaps the other
+// lanes' gates and shows up only as unexplained load to whatever is admitted next.
+//
+// **Every spelling collapses to the tool's name.** `command_memory.tool_calls_of` skips the wrapper
+// words (`pnpm`, `npx`, `exec`, env assignments) and reads a shell's quoted script (`sh -c '…'`,
+// `bash -c "…"`, `eval`) as the commands it runs, so `pnpm exec eslint`, `npx vitest`, `pnpm tsc`, a
+// bare `cspell` and any of them inside `sh -c` are all read as the program they launch. A
+// `pnpm josh …` reads as `josh` and passes — that is the budgeted path, and the command
+// `pnpm josh reserved-run <weight> -- <command>` wraps is read as reserved.
+//
+// **A multi-worker eslint is refused even when reserved** (joshuafolkken/kit#4582): typed eslint holds a
+// TypeScript program per worker, so `--concurrency 4` or `auto` held 12 GB in one lane and swapped the
+// machine. `--concurrency off`, `1` and no flag pass.
+//
+// **Lane children only.** An interactive session outside a lane keeps its direct runs; the overlap this
+// prevents is between concurrently dispatched lanes.
+//
+// **The commonest direct run is rewritten rather than refused** (joshuafolkken/kit#5147): the refusal's
+// reissue was the same line behind `pnpm josh reserved-run <weight> --`, a round trip the hook can make
+// itself. The weight is the gate's own for that tool — `core_weights.CORE_WEIGHTS`, and for vitest the
+// workers `command_memory.workers_of` reads — so the claim matches what the gate claims. `reserved-run`
+// runs its command as an argv, not a shell line, so only a line that is one command is wrapped: any
+// chain, pipe, redirection, group, substitution, comment, env prefix or timer leaves it to the refusal,
+// as does a multi-worker eslint, which no reservation makes safe. The wrapped line runs in the directory
+// it was typed in (`reserved-run.ts` → `command_directory`).
+
+const ESLINT = 'eslint'
+const VITEST = 'vitest'
+const HEAVY_TOOLS: ReadonlySet<string> = new Set([ESLINT, VITEST, 'cspell', 'tsc'])
+const TOOL_WEIGHTS: Readonly<Partial<Record<string, number>>> = {
+	[ESLINT]: core_weights.CORE_WEIGHTS.lint,
+	tsc: core_weights.CORE_WEIGHTS.type_check,
+	cspell: core_weights.CORE_WEIGHTS.spell_check,
+}
+const SINGLE_CORE = 1
+const RESERVED_RUN = 'pnpm josh reserved-run'
+// Read on the quote-blanked line: a quoted `;` or `|` is text. `2>&1` applies to the wrapper alike.
+const MULTI_COMMAND_SYNTAX = /[;|&<>()`#\n]|\$\(/u
+const KEPT_REDIRECT = /2>&1/gu
+const ENV_ASSIGNMENT = /^[A-Za-z_]\w*=/u
+
+const RESERVED_NOTE =
+	'↻ lane direct tool: a lane child ran a heavy tool directly, so the line was wrapped in ' +
+	'`pnpm josh reserved-run <weight> --` to claim its cores beside the other lanes. Prefer ' +
+	'`pnpm josh lint:related` / `test:related` / `cspell:dot` — `docs/josh-commands-automation.md`.'
+
+// The heavy tools the line launches outside a `reserved-run`. The cut is quote-aware, so a tool name
+// inside a quoted argument (`git commit -m "run eslint"`) is never read as a command; a quoted script
+// handed to a shell is.
+function direct_calls(command: string): Array<ToolCall> {
+	return command_memory
+		.tool_calls_of(command)
+		.filter((call) => !call.is_reserved && HEAVY_TOOLS.has(call.name))
+}
+
+// True when any command on the shell line launches one of the heavy tools outside a `reserved-run`.
+function runs_heavy_tool(command: string): boolean {
+	return direct_calls(command).length > 0
+}
+
+function weight_of(call: ToolCall, cores: number): number {
+	if (call.name === VITEST) return command_memory.workers_of(call, cores)
+
+	return TOOL_WEIGHTS[call.name] ?? SINGLE_CORE
+}
+
+// True when the whole line is one command, so a `reserved-run` can carry it as its argv.
+function is_one_command(command: string): boolean {
+	const judged = time_shell.blanked(command)
+
+	if (judged === undefined) return false
+
+	return (
+		!MULTI_COMMAND_SYNTAX.test(judged.replaceAll(KEPT_REDIRECT, ' ')) &&
+		!ENV_ASSIGNMENT.test(judged)
+	)
+}
+
+// A timed line stays as typed: `timed-rerun` reads the timer at the segment start, and a wrapper in front
+// would hide it from that row.
+function can_wrap(line: string, cores: number): boolean {
+	if (!is_one_command(line) || timed_rerun.is_timed_run(line)) return false
+
+	return !command_memory.runs_multi_worker_eslint(line, cores)
+}
+
+// The line behind `reserved-run` at its largest tool's weight, or `undefined` where it must be refused.
+function reserved_command(
+	command: string,
+	cores: number = os.availableParallelism(),
+): string | undefined {
+	const line = command.trim()
+	const calls = direct_calls(line)
+
+	if (!can_wrap(line, cores) || calls.length === 0) return undefined
+
+	const weight = Math.max(...calls.map((call) => weight_of(call, cores)))
+
+	return `${RESERVED_RUN} ${String(weight)} -- ${line}`
+}
+
+function is_lane_bash(call: GuardedCall): boolean {
+	return call.name === cost_blocks.BASH_TOOL && lane_child_marker.is_child_of(process.cwd())
+}
+
+// The call's input with its line wrapped, for a lane child alone; `undefined` where nothing is rewritten.
+function reserved_input(call: GuardedCall): Record<string, unknown> | undefined {
+	if (!is_lane_bash(call) || !json_value.is_record(call.input)) return undefined
+
+	const command = reserved_command(time_shell.bash_command(call.input))
+
+	return command === undefined ? undefined : { ...call.input, command }
+}
+
+// True when this session is a dispatched lane child launching a heavy tool directly, or eslint with
+// more than one worker by any path.
+function is_lane_direct_tool(
+	command: string,
+	is_lane_child: boolean = lane_child_marker.is_child_of(process.cwd()),
+): boolean {
+	if (!is_lane_child) return false
+
+	return runs_heavy_tool(command) || command_memory.runs_multi_worker_eslint(command)
+}
+
+const LANE_DIRECT_TOOL_REASON =
+	'⛔ lane child running `eslint` / `vitest` / `cspell` / `tsc` directly, or multi-worker eslint: ' +
+	'it overlaps the other lanes. Run `pnpm josh lint:related`, `pnpm josh test:related`, ' +
+	'`pnpm josh cspell:dot` or `pnpm josh reserved-run <weight> -- <command>`, eslint at ' +
+	'`--concurrency off`. Only a one-command line is wrapped for you. Refused on every occurrence.'
+
+// The row itself, so `delivered-rules.ts` spreads one entry; the shape is `lane-switch-main.ts`'s.
+const ROW = {
+	id: 'lane-direct-tool',
+	is_trigger: bash_triggers.on_bash_command(is_lane_direct_tool),
+	reason: LANE_DIRECT_TOOL_REASON,
+	decide: (): boolean => true,
+	rewrite: reserved_input,
+	rewrite_note: RESERVED_NOTE,
+	about: {
+		title: 'Lane child running a heavy tool directly',
+		topic: '`docs/josh-commands-automation.md` → `josh reserved-run`',
+		fires:
+			"a dispatched lane child launching `eslint` / `vitest` / `cspell` / `tsc` (bare, `pnpm exec`, `npx`, inside `sh -c`), or eslint with `--concurrency` other than `off` / `1` by any path, `reserved-run` included. A one-command line is rewritten behind `pnpm josh reserved-run <weight> --` at the gate's weight; a chained, piped, redirected or env-prefixed line and a multi-worker eslint are refused, every occurrence",
+		quiet: 'not a lane child, or the run goes through `pnpm josh` with single-worker eslint',
+	},
+}
+
+const lane_direct_tool = {
+	LANE_DIRECT_TOOL_REASON,
+	RESERVED_NOTE,
+	ROW,
+	is_lane_direct_tool,
+	reserved_command,
+	reserved_input,
+	runs_heavy_tool,
+}
+
+export { lane_direct_tool }

package/scripts/rules/lane-interactive-ask.ts

@@ -1,6 +1,7 @@
 import { interactive_ask } from '#scripts/agent/interactive-ask'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
 import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
+import { stop_rules } from './stop-rules'
 
 // A dispatched lane child's interactive ask is refused and routed to the park procedure, delivered at
 // the call it binds on.
@@ -43,8 +44,7 @@ function is_interactive_ask(
 const LANE_INTERACTIVE_ASK_REASON =
 	'⛔ lane child interactive ask: this session is a dispatched lane child and cannot ask a ' +
 	'person, so park instead: ' +
-	"`gh api repos/{owner}/{repo}/issues/<N>/labels -f 'labels[]=needs-decision'`, " +
-	'`pnpm josh issue:comment <N> --body-file <path>`, ' +
+	'`pnpm josh run:park <N> --body-file <path>` (it applies `needs-decision`), ' +
 	'the `confirmation` Telegram, stop. It fires on every occurrence ' +
 	'(`.claude/skills/workflow-commands/pre-gate-cut.md`, `backlogrun-park.md`).'
 
@@ -56,6 +56,16 @@ const ROW = {
 	is_trigger: is_interactive_ask,
 	reason: LANE_INTERACTIVE_ASK_REASON,
 	decide: (): boolean => true,
+	// A reply asking a person for the git index is the same ask, delivered by the Stop hook.
+	stop_reasons: [stop_rules.LANE_INDEX_REASON],
+	about: {
+		title: 'Lane child interactive ask',
+		topic:
+			'`.claude/skills/workflow-commands/pre-gate-cut.md` → "The interactive ask is refused one call earlier"',
+		fires:
+			"a dispatched lane child's `AskUserQuestion`; it hands over the park procedure; the Stop hook also blocks a reply asking a person for the git index. Every occurrence",
+		quiet: 'not a lane child, or not an interactive tool',
+	},
 }
 
 const lane_interactive_ask = { LANE_INTERACTIVE_ASK_REASON, ROW, is_interactive_ask }

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 { run_park } from '#scripts/run/park/run-park'
 import { bash_triggers } from './bash-triggers'
 import { shell_segments } from './shell-segments'
 
@@ -19,15 +20,12 @@ import { shell_segments } from './shell-segments'
 // confirmation` is the call every lane-child stop passes through. The agent that obeys this is always
 // a `claude -p` child, so the rule leaves residency entirely (`prompts/collaboration-workflow/rule-delivery.md`).
 //
-// **Why once per run and not a synchronous compliance check.** The pre-gate cut can stay silent on a
-// compliant run because the cut record is a local file it reads synchronously; the park is a label on
-// GitHub, which a `PreToolUse` guard cannot read (it answers synchronously, network calls are out).
-// Scanning the transcript tail for the label instead is unsafe in the one direction that matters: a
-// child that merely *read* `backlogrun-park.md`, whose prose carries the very `labels[]=needs-decision`
-// command, would look compliant and the guard would fall silent on a real violation — the whole bug,
-// reappearing inside its own check. So the row carries no `already_satisfied`: it fires once per run on
-// the stop, the reason is a checklist rather than an accusation, and a child that already parked simply
-// reissues. One wasted round trip on the compliant path is the safe direction; a missed park is not.
+// **A parked child is silent, read off the local park record.** The park is a label on GitHub, which a
+// `PreToolUse` guard cannot read (it answers synchronously, network calls are out), and scanning the
+// transcript tail for the label is unsafe: a child that merely *read* `backlogrun-park.md` would look
+// compliant. So `pnpm josh run:park` writes a local record once the comment and the label are both on
+// the issue, and the guard reads it synchronously, the way the pre-gate cut guard reads the cut record
+// (joshuafolkken/kit#4132). A child with no record still gets the once-per-run checklist.
 
 // `josh notify`, named canonically — `shell_segments.is_josh_command` expands an alias before the match.
 const NOTIFY_COMMANDS: ReadonlySet<string> = new Set(['notify'])
@@ -85,48 +83,73 @@ function is_parking_child(directory: string = process.cwd()): boolean {
 	return lane_child_marker.is_child_of(directory) && !lane_handoff.is_handed_off(directory)
 }
 
-function is_unparked_stop(command: string, is_child: () => boolean = is_parking_child): boolean {
+// A parking child that has not parked yet: `run:park` left no record for its issue in this repository.
+// Kept apart from `is_parking_child`, which `run:entry` reads to leave a lane child's stop to this row
+// whether or not it has parked.
+function is_unparked_child(directory: string = process.cwd()): boolean {
+	if (!is_parking_child(directory)) return false
+
+	const issue = lane_child_marker.marked_issue()
+
+	return issue === undefined || !run_park.is_parked_sync(issue, directory)
+}
+
+function is_unparked_stop(command: string, is_child: () => boolean = is_unparked_child): boolean {
 	if (!is_confirmation_notify(command)) return false
 
 	return is_child()
 }
 
 // **Keeping this rule is applying `needs-decision`**, the one act the park asks for before the stop.
-// It reads an actual `Bash` command — a label application by REST or by `gh issue edit` — never the
-// transcript tail, so a doc read that quotes the command is not mistaken for the run making it.
+// It reads an actual `Bash` command — `josh run:park`, or a label application by REST or by
+// `gh issue edit` — never the transcript tail, so a doc read that quotes the command is not mistaken
+// for the run making it. `run:park --clear` takes the park off, so it is not one.
 const APPLIES_NEEDS_DECISION = new RegExp(
 	String.raw`(?:labels\[\]=|--add-label[= ]'?)${NEEDS_DECISION_LABEL}\b`,
 	'u',
 )
+const PARK_COMMANDS: ReadonlySet<string> = new Set(['run:park'])
+const CLEAR_FLAG = /(?:^|\s)--clear\b/u
+
+function is_park_command(segment: string): boolean {
+	return shell_segments.is_josh_command(segment, PARK_COMMANDS) && !CLEAR_FLAG.test(segment)
+}
 
 function records_the_park(command: string): boolean {
-	return APPLIES_NEEDS_DECISION.test(command)
+	if (APPLIES_NEEDS_DECISION.test(command)) return true
+
+	return shell_segments.segments_of(command).some((segment) => is_park_command(segment))
 }
 
 // The instruction in the shape a refusal can carry: what the stop must leave behind, how to record it,
-// and the reissue sentence every delivery needs. **The park procedure is named, not restated** — the
+// and that the park is the stop itself — no notify follows it, since the `Stop` hook sends one still owed
+// on the hold (`stop-rules.ts` → `needs_notify`). **The park procedure is named, not restated** — the
 // single source is `backlogrun-park.md` → "park and continue", and a second copy here would be the
 // clone `CLAUDE.md` prohibits.
 const LANE_PARK_REASON =
 	'⛔ lane child park: this session is a dispatched lane child, so a stop for a person parks first: ' +
-	"`gh api repos/{owner}/{repo}/issues/<N>/labels -f 'labels[]=needs-decision'`; " +
-	'`pnpm josh issue:comment <N> --body-file <path>` (question, options, stash); a ' +
-	'`needs-human-review` / `already-done` stop already is. Reissue this notify, once per run ' +
+	'`pnpm josh run:park <N> --body-file <path>` (question, options, stash — it applies ' +
+	'`needs-decision`); a ' +
+	'`needs-human-review` / `already-done` stop already is. The park is the stop: no notify ' +
+	'after it. Refused once per run ' +
 	'(`.claude/skills/workflow-commands/pre-gate-cut.md`).'
 
-// 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 `decide` is 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.
+// The row itself, so `delivered-rules.ts` spreads one entry. **Once per run rather than `decide`.** The
+// stop ends the turn, so it is not the recurring act `decide` is for. A parked child is excluded in the
+// trigger itself (`is_unparked_child`), so the park record is the satisfaction and no
+// `already_satisfied` reads the tail. `keeps` reads an actual park `Bash` command, never the tail, so a
+// doc read that quotes one is not mistaken for it.
 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),
+	about: {
+		title: 'Lane child park',
+		topic: '`.claude/skills/workflow-commands/pre-gate-cut.md`',
+		fires: 'a dispatched lane child issuing `pnpm josh notify --task-type confirmation`',
+		quiet: 'not a lane child, or not a stop notification',
+	},
 }
 
 const lane_park = {
@@ -135,6 +158,7 @@ const lane_park = {
 	ROW,
 	is_confirmation_notify,
 	is_parking_child,
+	is_unparked_child,
 	is_unparked_stop,
 	mentions_confirmation_notify,
 	records_the_park,