@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/hooks/format-edited-file.ts

@@ -1,11 +1,11 @@
 #!/usr/bin/env tsx
 import { existsSync } from 'node:fs'
 import path from 'node:path'
-import { fileURLToPath } from 'node:url'
-import { resolve_local_bin, resolve_package_bin } from '#scripts/build/local-bin'
+import { resolve_local_bin } from '#scripts/build/local-bin'
 import { ESLINT_EDIT_CACHE_FLAGS } from '#scripts/josh/josh-command-types'
 import { json_value } from '#scripts/lib/json-value'
 import { HOOK_PROCESS_TIMEOUT_MS } from '#scripts/lib/timeouts'
+import { eslint_daemon } from '#scripts/lint/eslint-daemon'
 import { time_density_hook } from '#scripts/time-runtime/time-density-hook'
 import { execa } from 'execa'
 import { z } from 'zod'
@@ -83,12 +83,8 @@ const ESLINT_ARGUMENTS: ReadonlyArray<string> = [
 // identical rather than merely similar. The config entry file is re-read per request; the modules it
 // imports are not, which `plan_daemon_restart` below is the answer to. The daemon exits after 15
 // minutes of inactivity.
-const ESLINT_DAEMON = 'eslint_d'
+const { ESLINT_DAEMON } = eslint_daemon
 const DAEMON_RESTART = 'restart'
-// The two shapes a flat config is built from here and in every consumer of this kit: the root
-// `eslint.config.*` entry, and the rule modules under `eslint/` that it imports.
-const ESLINT_CONFIG_DIR = 'eslint'
-const ESLINT_CONFIG_ENTRY = /^eslint\.config\.[cm]?[jt]s$/u
 
 // The problems eslint could not auto-fix are handed to the model verbatim from eslint's own stdout —
 // its default formatter already prints the file, the `line:col`, and the rule name. A header names what the block is, since additionalContext arrives
@@ -104,11 +100,6 @@ const DIAGNOSTIC_TRUNCATION_NOTICE = '\n…(diagnostics truncated)'
 // present.
 const SECTION_SEPARATOR = '\n\n'
 
-// Where this file sits inside the kit package. `eslint_d` is kit's dependency rather than the
-// consumer's, and pnpm writes a `node_modules/.bin` shim only for a project's *direct* dependencies,
-// so a consumer's project root cannot see it and this directory can.
-const MODULE_DIRECTORY = path.dirname(fileURLToPath(import.meta.url))
-
 interface FormatCommand {
 	bin: string
 	command_arguments: ReadonlyArray<string>
@@ -226,10 +217,7 @@ const DAEMON_BINS: ReadonlySet<string> = new Set([ESLINT_BIN, ESLINT_DAEMON])
 function resolve_daemon_cli(bin: string, project_root: string): string | undefined {
 	if (!DAEMON_BINS.has(bin)) return undefined
 
-	return (
-		resolve_package_bin(MODULE_DIRECTORY, ESLINT_DAEMON, ESLINT_DAEMON) ??
-		resolve_package_bin(project_root, ESLINT_DAEMON, ESLINT_DAEMON)
-	)
+	return eslint_daemon.resolve_daemon_cli(project_root)
 }
 
 // Only the config *entry file* is re-read per request: ESLint cache-busts `eslint.config.js` by
@@ -238,13 +226,6 @@ function resolve_daemon_cli(bin: string, project_root: string): string | undefin
 // and then any source file, and it would be auto-fixed against the pre-edit rules for as long as the
 // daemon lives — an author testing a rule change would read that as the rule being broken. Restarting
 // after an edit to a config input is what makes the whole config current, not just its first file.
-function is_eslint_config_input(relative_path: string): boolean {
-	return (
-		relative_path.split(path.sep)[0] === ESLINT_CONFIG_DIR ||
-		ESLINT_CONFIG_ENTRY.test(relative_path)
-	)
-}
-
 function plan_daemon_restart(
 	file_path: string,
 	project_root: string,
@@ -253,7 +234,7 @@ function plan_daemon_restart(
 
 	if (
 		relative === undefined ||
-		!is_eslint_config_input(relative) ||
+		!eslint_daemon.is_config_input(relative) ||
 		resolve_daemon_cli(ESLINT_DAEMON, project_root) === undefined
 	) {
 		return []
@@ -379,6 +360,19 @@ async function collect_unfixed(
 	return unfixed
 }
 
+// The edited file as the daemon read it, or nothing when no eslint command linted it — a `.json`
+// module prettier alone formats is still in the type program, and a refreshed record would hide its
+// old copy there (joshuafolkken/kit#4867).
+function linted_path(
+	plan: ReadonlyArray<FormatCommand>,
+	file_path: string,
+	project_root: string,
+): string | undefined {
+	if (plan.every((command) => command.bin !== ESLINT_BIN)) return undefined
+
+	return relative_to_root(project_root, file_path)
+}
+
 async function format_edited_file(
 	raw_payload: string,
 	runner: CommandRunner,
@@ -392,8 +386,15 @@ async function format_edited_file(
 		...plan_commands(file_path, project_root),
 		...plan_daemon_restart(file_path, project_root),
 	]
+	const daemon_before = eslint_daemon.read_record(project_root)
 	const unfixed = await collect_unfixed(plan, runner, project_root)
 
+	eslint_daemon.remember_after_edit(
+		project_root,
+		daemon_before,
+		linted_path(plan, file_path, project_root),
+	)
+
 	return format_diagnostics(unfixed === '' ? undefined : unfixed)
 }
 
@@ -460,15 +461,18 @@ function report_no_payload(): void {
 // its content before the formatters ran against its content after — so it too is known only once they
 // have. The rewrite, lint and spell blocks are composed together first, then
 // joined to the density line — one envelope, since a `PostToolUse` hook's stdout carries only one.
+// The spell check runs beside the formatters rather than after them, on the text as the edit left it:
+// it was the hook's largest step (joshuafolkken/kit#4596), and a formatter rewrites layout, not words.
 // A hook killed at its 15s timeout is the one case this loses the density
 // line to — a run already gone pathologically wrong, per HOOK_PROCESS_TIMEOUT_MS.
 async function run_hook(payload: string): Promise<void> {
 	const notice = time_density_hook.density_notice(payload)
 	const file_path = parse_edited_path(payload)
 	const before = rewrite_notice.read_text(file_path)
+	const pending_spelling = edited_cspell.spelling_diagnostics(file_path, process.cwd(), before)
 	const lint = await format_edited_payload(payload, process.cwd())
 	const rewrite = rewrite_notice.build(before, rewrite_notice.read_text(file_path))
-	const spelling = await edited_cspell.spelling_diagnostics(file_path, process.cwd())
+	const spelling = await pending_spelling
 	const parts = compose_context(rewrite, compose_context(lint, spelling))
 	const context = compose_context(notice, parts)
 

package/scripts/hooks/lane-plan-guard.ts

@@ -0,0 +1,50 @@
+import { lane_child_marker, type MarkerSource } from '#scripts/lane/lane-child-marker'
+import { lane_plan } from '#scripts/lane/lane-plan'
+import { step_zero_notice } from './step-zero-notice'
+
+// A dispatched lane child's first implementation edit is refused until `josh lane:plan` has recorded
+// the files its work summary changes and cleared them (joshuafolkken/kit#4864). The record is what holds a later lane
+// back from those files, so it has to exist before the code does; a document asking for it would be
+// read after the edit it governs.
+//
+// **A dispatched lane child only**, the trust condition `lane-phase.ts` applies: a person's session, or
+// one carrying a mark leaked from a parent, runs no lanes beside it to wait on.
+
+const COMMAND_DOC = '`docs/josh-commands-run.md` → "`josh lane:plan`"'
+const OUTCOMES =
+	'on `yield` end the session with no edit (its lane is given back); on `wait` run it again'
+
+function reason_text(issue: string): string {
+	const command = `\`pnpm josh lane:plan ${issue} <path>...\``
+
+	return `⛔ lane plan: run ${command} naming every file the work summary changes before the first implementation edit — ${OUTCOMES} (${COMMAND_DOC}).`
+}
+
+// The issue of the dispatched lane child making this runtime edit, or `undefined` for any other call.
+function lane_child_edit(
+	raw_payload: string,
+	directory: string,
+	source: MarkerSource,
+): string | undefined {
+	if (!lane_child_marker.is_child_of(directory, source)) return undefined
+
+	return step_zero_notice.is_runtime_edit(raw_payload, directory)
+		? lane_child_marker.marked_issue(source)
+		: undefined
+}
+
+function reason(
+	raw_payload: string,
+	directory: string = process.cwd(),
+	source: MarkerSource = process.env,
+): string | undefined {
+	const issue = lane_child_edit(raw_payload, directory, source)
+
+	if (issue === undefined) return undefined
+
+	return lane_plan.is_uncleared(Number(issue), directory) ? reason_text(issue) : undefined
+}
+
+const lane_plan_guard = { reason }
+
+export { lane_plan_guard }

package/scripts/hooks/pre-commit-lint-switch.ts

@@ -0,0 +1,9 @@
+// **Switched off, a pre-commit lint hook neither reserves the core budget nor runs** — set by `josh
+// ship`'s local commit (`run-ship-sync.ts`), whose tree the gate or the scoped pair checks before
+// anything is pushed (joshuafolkken/kit#4985). On by default like every other distributed guard. Its
+// own module because the hook is an entry with a main guard, which nothing may import.
+const SWITCH_ENV_KEY = 'JOSH_PRE_COMMIT_LINT'
+
+const pre_commit_lint_switch = { SWITCH_ENV_KEY }
+
+export { pre_commit_lint_switch }

package/scripts/hooks/pre-commit-lint.ts

@@ -1,12 +1,18 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { core_budget } from '#scripts/gate/core-budget'
+import { pre_commit_lint_switch } from '#scripts/hooks/pre-commit-lint-switch'
+import { hook_decision } from '#scripts/josh/hook-decision'
 import {
 	CSPELL_COMMIT_CACHE_FLAGS,
+	ESLINT_COMMIT_CACHE_FILE,
 	ESLINT_COMMIT_CACHE_FLAGS,
 	PRETTIER_CACHE_FLAGS,
 } from '#scripts/josh/josh-command-types'
+import { FAIL_EXIT_CODE } from '#scripts/lib/buffered-process'
 import { resolve_spawn_exit } from '#scripts/lib/spawn-exit'
+import { eslint_cache_dependencies } from '#scripts/lint/eslint-cache-dependencies'
+import { eslint_daemon } from '#scripts/lint/eslint-daemon'
 import { execa } from 'execa'
 
 // The pre-commit hook's cspell, prettier and eslint runs over the staged files. They go through here
@@ -21,6 +27,7 @@ import { execa } from 'execa'
 const ARGV_OFFSET = 2
 const USAGE_ERROR_EXIT_CODE = 2
 const PNPM = 'pnpm'
+const ESLINT = 'eslint'
 
 const TOOL_ARGUMENTS: Readonly<Record<string, ReadonlyArray<string>>> = {
 	cspell: [
@@ -46,8 +53,13 @@ const TOOL_BUDGETS: Readonly<Record<string, 'spell_check' | 'format' | 'eslint_s
 	eslint: 'eslint_scan',
 }
 
+const SUCCESS_EXIT_CODE = 0
+
 const USAGE = `Usage: josh pre-commit-lint <${Object.keys(TOOL_ARGUMENTS).join('|')}> [files...]`
+const END_OF_OPTIONS = '--'
 
+// The staged files follow `--`, so a file named `--plugin=x.mjs` is read as a file, never as an
+// option that loads code (joshuafolkken/kit#4634).
 function build_arguments(
 	tool: string,
 	staged_files: ReadonlyArray<string>,
@@ -55,7 +67,23 @@ function build_arguments(
 	const tool_arguments = TOOL_ARGUMENTS[tool]
 	if (tool_arguments === undefined) return undefined
 
-	return [...tool_arguments, ...staged_files]
+	return [...tool_arguments, END_OF_OPTIONS, ...staged_files]
+}
+
+// eslint goes through the lane's warm daemon when one is reachable (joshuafolkken/kit#4358): the same
+// argument list and the same cache file, without paying the config and plugin load per commit. It
+// runs inside the tool's core-budget reservation like the cold route does.
+//
+// A merge or checkout can change only the files a staged file imports, and the content cache keeps
+// the staged file's verdict: its entry is dropped first when they changed (joshuafolkken/kit#4415).
+async function run_eslint(command_arguments: ReadonlyArray<string>): Promise<number> {
+	const result = await eslint_cache_dependencies.guard(
+		ESLINT_COMMIT_CACHE_FILE,
+		async () => await eslint_daemon.run_or_cold(command_arguments),
+	)
+	if (result.output !== '') process.stdout.write(result.output)
+
+	return result.exit_code ?? FAIL_EXIT_CODE
 }
 
 async function run_tool(command_arguments: ReadonlyArray<string>): Promise<number> {
@@ -64,20 +92,32 @@ async function run_tool(command_arguments: ReadonlyArray<string>): Promise<numbe
 	return resolve_spawn_exit(PNPM, result)
 }
 
+async function run_reserved(tool: string, staged_files: ReadonlyArray<string>): Promise<number> {
+	const command_arguments = build_arguments(tool, staged_files) ?? []
+	if (tool === ESLINT) return await run_eslint(command_arguments)
+
+	return await run_tool(command_arguments)
+}
+
+function is_switched_on(): boolean {
+	return hook_decision.is_switch_enabled(pre_commit_lint_switch.SWITCH_ENV_KEY)
+}
+
 async function run(argv: ReadonlyArray<string>): Promise<number> {
 	const [tool = '', ...staged_files] = argv
-	const command_arguments = build_arguments(tool, staged_files)
 	const budget = TOOL_BUDGETS[tool]
 
-	if (command_arguments === undefined || budget === undefined) {
+	if (budget === undefined) {
 		console.error(USAGE)
 
 		return USAGE_ERROR_EXIT_CODE
 	}
 
+	if (!is_switched_on()) return SUCCESS_EXIT_CODE
+
 	return await core_budget.with_command_reservation(
 		core_budget.CORE_WEIGHTS[budget],
-		async () => await run_tool(command_arguments),
+		async () => await run_reserved(tool, staged_files),
 		{ memory_mb: core_budget.MEMORY_MB[budget], command: `pre-commit ${tool}` },
 	)
 }

package/scripts/hooks/pre-push-related-switch.ts

@@ -0,0 +1,10 @@
+// **Switched on, a pre-push unit run the gate record does not cover runs the related tests rather than
+// the whole suite** — set by `josh ship`'s push ahead of the gate (`run-ship-sync.ts`), whose gate over
+// the same tree runs the whole suite next (joshuafolkken/kit#5067). Off by default. Its own module
+// because the hook is an entry with a main guard, which nothing may import.
+const SWITCH_ENV_KEY = 'JOSH_PRE_PUSH_RELATED'
+const SWITCH_ON = '1'
+
+const pre_push_related_switch = { SWITCH_ENV_KEY, SWITCH_ON }
+
+export { pre_push_related_switch }

package/scripts/hooks/pre-push-unit.ts

@@ -5,7 +5,10 @@ import { gate_plan } from '#scripts/gate/gate-plan'
 import { gate_skip, type GateReuse } from '#scripts/gate/gate-skip'
 import { gate_tree, type GateTree } from '#scripts/gate/gate-tree'
 import { hook_gate_reuse } from '#scripts/gate/hook-gate-reuse'
+import type { PushMissRecord } from '#scripts/lane/lane-ledger-schema'
+import { lane_ledger_write } from '#scripts/lane/lane-ledger-write'
 import { test_unit_guard } from '#scripts/test/test-unit-guard'
+import { pre_push_related_switch } from './pre-push-related-switch'
 
 // The pre-push hook's unit run, which does not re-run a suite a green gate already covers: the gate
 // writes its record down, and re-running `vitest run` on a tree it just printed green is the bulk of
@@ -125,28 +128,93 @@ function format_miss(reason: string): string {
 	return `↻ running the whole unit suite — the green gate record does not cover this push: ${reason}.`
 }
 
-// **The whole suite claims its place in the core budget, the one `josh test:unit` claims.** Without it
-// a push's suite ran beside other lanes' gates off the ledger, so their admission saw its workers only
-// as foreign load (joshuafolkken/kit#3874). Only the miss reserves: a reused record runs nothing, and a
+// **A unit run claims its place in the core budget, the one `josh test:unit` claims.** Without it a
+// push's run went beside other lanes' gates off the ledger, so their admission saw its workers only as
+// foreign load (joshuafolkken/kit#3874). Only the miss reserves: a reused record runs nothing, and a
 // claim there could make a push wait out a full ledger for a suite it then skips.
+async function run_reserved(command: string, run: () => Promise<number>): Promise<number> {
+	const claim = gate_plan.DIRECT_UNIT_CLAIM
+
+	return await core_budget.with_command_reservation(claim.core_weight(), run, {
+		memory_mb: claim.memory_mb(),
+		command,
+		is_unit: claim.is_unit_claim,
+	})
+}
+
 async function run_reserved_suite(vitest_arguments: ReadonlyArray<string>): Promise<number> {
-	return await core_budget.with_command_reservation(
-		gate_plan.direct_unit_weight(),
+	return await run_reserved(
+		'pre-push test:unit',
 		async () => await test_unit_guard.run_guarded_unit(process.cwd(), vitest_arguments),
-		{ memory_mb: gate_plan.direct_unit_memory(), command: 'pre-push test:unit' },
 	)
 }
 
+// **A push its caller makes ahead of the gate runs the related tests, not the whole suite**
+// (joshuafolkken/kit#5067). `josh ship` pushes the tree its sync merged with the default branch onto an
+// open pull request so CI starts beside the gate, and the gate that follows runs the whole suite over
+// that same tree; the push itself only needs what this branch's change reaches. Only the caller sets
+// it, `--force` and the escape hatch still win, and a narrowed run asked for its own arguments rather
+// than this scope.
+function is_related_requested(extra_arguments: ReadonlyArray<string>): boolean {
+	const { SWITCH_ENV_KEY, SWITCH_ON } = pre_push_related_switch
+
+	if (process.env[SWITCH_ENV_KEY] !== SWITCH_ON || extra_arguments.length > 0) return false
+
+	return !hook_gate_reuse.is_force_requested(FORCE_ENV)
+}
+
+function format_related(reason: string): string {
+	return `↻ running the related unit tests — the push runs ahead of its gate, and the green gate record does not cover it: ${reason}.`
+}
+
+// Imported only on this path, so every other push leaves the import graph `test-related.ts` loads alone.
+async function run_related(): Promise<number> {
+	const { test_related } = await import('#scripts/test/test-related')
+
+	return await run_reserved(
+		'pre-push test:related',
+		async () => await test_related.run_related_tests([]),
+	)
+}
+
+// joshuafolkken/kit#5234: the miss's kind goes to the lane ledger, so `lane:stats` counts the suites a
+// push ran and why beside the gate's own fallbacks.
+async function record_miss(scope: PushMissRecord['scope'], kind: string): Promise<void> {
+	await lane_ledger_write.record_push_miss({ scope, reason: kind })
+}
+
+async function run_miss(
+	reason: string,
+	kind: string,
+	extra_arguments: ReadonlyArray<string>,
+): Promise<number> {
+	if (is_related_requested(extra_arguments)) {
+		process.stdout.write(`${format_related(reason)}\n`)
+		await record_miss('related', kind)
+
+		return await run_related()
+	}
+
+	process.stdout.write(`${format_miss(reason)}\n`)
+	await record_miss('whole', kind)
+
+	return await run_reserved_suite(forwarded_arguments(extra_arguments))
+}
+
 async function run_pre_push_unit(
 	extra_arguments: ReadonlyArray<string> = [],
 	source?: string,
 ): Promise<number> {
-	const reuse = push_reuse(await read_push_tree(), extra_arguments, source)
+	const tree = await read_push_tree()
+	const reuse = push_reuse(tree, extra_arguments, source)
 
 	if ('miss' in reuse) {
-		process.stdout.write(`${format_miss(reuse.miss)}\n`)
+		const kind = hook_gate_reuse.miss_kind(reuse.miss, {
+			carry_miss: tree.carry_miss,
+			force_env: FORCE_ENV,
+		})
 
-		return await run_reserved_suite(forwarded_arguments(extra_arguments))
+		return await run_miss(reuse.miss, kind, extra_arguments)
 	}
 
 	process.stdout.write(`${format_skip(reuse.stamp.taken_at)}\n`)

package/scripts/hooks/pretool-guard-cli.ts

@@ -1,5 +1,4 @@
 #!/usr/bin/env tsx
-import { text } from 'node:stream/consumers'
 import { fileURLToPath } from 'node:url'
 import { hook_decision } from '#scripts/josh/hook-decision'
 import { pretool_guard } from './pretool-guard'
@@ -11,11 +10,5 @@ import { pretool_guard } from './pretool-guard'
 // `dist/hooks/pretool-guard.js`, so the bundled hook ran no guard at all and every refusal failed open.
 // An entry nothing imports keeps the self-invoke in the file that is actually launched.
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
-	if (process.stdin.isTTY) hook_decision.report_no_payload('pretool:guard')
-	else {
-		const raw_payload = await text(process.stdin)
-
-		hook_decision.load_environment_file()
-		await pretool_guard.respond(raw_payload)
-	}
+	await hook_decision.respond_from_stdin('pretool:guard', pretool_guard.respond)
 }

package/scripts/hooks/pretool-guard.ts

@@ -11,6 +11,8 @@ import { run_poll_hook } from '#scripts/run/run-poll-hook'
 import { run_watcher_hook } from '#scripts/run/run-watcher-hook'
 import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
 import { batch_outcome } from './batch-guard'
+import { lane_plan_guard } from './lane-plan-guard'
+import { shell_rules_notice } from './shell-rules-notice'
 import { step_zero_notice } from './step-zero-notice'
 
 // One PreToolUse process for the three guards that used to be three. A Bash
@@ -52,12 +54,13 @@ function combine_outcomes(
 	return outcomes.find((outcome) => !is_clear(outcome)) ?? CLEAR
 }
 
-// The Step 0 reminder is the last word: asked only where every guard stayed
-// clear, so a refusal or another notice never spends its once-per-session stamp unseen.
-function with_step_zero_notice(outcome: GuardOutcome, raw_payload: string): GuardOutcome {
+// The once-per-session reminders are the last word: asked only where every guard stayed clear, so a
+// refusal or another notice never spends their stamps unseen. Step 0 answers an edit and the shell
+// rules a Bash call, so at most one of them speaks on a call.
+function with_session_notice(outcome: GuardOutcome, raw_payload: string): GuardOutcome {
 	if (!is_clear(outcome)) return outcome
 
-	const notice = step_zero_notice.notice(raw_payload)
+	const notice = step_zero_notice.notice(raw_payload) ?? shell_rules_notice.notice(raw_payload)
 
 	return notice === undefined ? outcome : { reason: undefined, notice, fault: undefined }
 }
@@ -70,14 +73,15 @@ function guard_outcome(raw_payload: string): GuardOutcome {
 		batch_outcome(raw_payload),
 		investigation_outcome(raw_payload),
 		duplicate_read_outcome(raw_payload),
+		{ reason: lane_plan_guard.reason(raw_payload), notice: undefined, fault: undefined },
 	]
 
 	return combine_outcomes(outcomes, delivered_rules.delivery(raw_payload))
 }
 
-// The synchronous verdict the Codex adapter asks for, with the Step 0 reminder as its last layer.
+// The synchronous verdict the Codex adapter asks for, with the session reminders as its last layer.
 function pretool_outcome(raw_payload: string): GuardOutcome {
-	return with_step_zero_notice(guard_outcome(raw_payload), raw_payload)
+	return with_session_notice(guard_outcome(raw_payload), raw_payload)
 }
 
 // The Step 0 notice fires once, on the first runtime-file edit: the moment a lane child's plan turns
@@ -116,7 +120,7 @@ async function pretool_outcome_async(raw_payload: string): Promise<GuardOutcome>
 
 	if (reason !== undefined) return { reason, notice: undefined, fault: undefined }
 
-	const outcome = with_step_zero_notice(base, raw_payload)
+	const outcome = with_session_notice(base, raw_payload)
 
 	await mark_phase(outcome)
 
@@ -140,26 +144,36 @@ function rewrite_context(note: string, outcome: GuardOutcome): string {
 	return [note, outcome.notice ?? outcome.fault].filter(Boolean).join('\n\n')
 }
 
-// The envelope that replaces the outcome's own when a lane child backgrounded `josh ship` alone:
-// the call is run in the foreground instead of being refused. A refusal from
-// any guard still wins, and a notice the outcome carried rides along in the same context.
+function foreground_input_of(
+	raw_payload: string,
+	is_lane_child?: () => boolean,
+): Record<string, unknown> | undefined {
+	const call = guarded_call(raw_payload)
+
+	return call === undefined ? undefined : lane_background.foreground_input(call, is_lane_child)
+}
+
+// The envelope that replaces the outcome's own when a lane child runs `josh ship` alone: the call is
+// run in the foreground at the cap instead of being refused or moved aside. A refusal from any guard
+// still wins, and a notice the outcome carried rides along in the same context. On top of a row's
+// rewrite — `raw_payload` is then the rewritten call — it keeps that row's notes and its lack of a
+// permission decision, so the cap is never lost to a pipefail or tail rewrite (joshuafolkken/kit#4101).
 function foreground_rewrite(
 	outcome: GuardOutcome,
 	raw_payload: string,
 	is_lane_child?: () => boolean,
+	rewrite?: RuleRewrite,
 ): string | undefined {
-	if (outcome.reason !== undefined) return undefined
-
-	const call = guarded_call(raw_payload)
 	const input =
-		call === undefined ? undefined : lane_background.foreground_input(call, is_lane_child)
+		outcome.reason === undefined ? foreground_input_of(raw_payload, is_lane_child) : undefined
 
 	if (input === undefined) return undefined
 
-	return hook_decision.rewrite_envelope(
-		input,
-		rewrite_context(lane_background.FOREGROUND_NOTE, outcome),
-	)
+	const note = [rewrite?.note, lane_background.FOREGROUND_NOTE].filter(Boolean).join('\n\n')
+	const envelope_of =
+		rewrite === undefined ? hook_decision.rewrite_envelope : hook_decision.flow_rewrite_envelope
+
+	return envelope_of(input, rewrite_context(note, outcome))
 }
 
 // The rows' rewrite carries no permission decision: whatever else the line runs meets its own prompt.
@@ -174,7 +188,8 @@ function rule_envelope(
 
 // The hook's one write: a rewrite where one applies, the outcome's own envelope otherwise.
 function emit(raw_payload: string, outcome: GuardOutcome, rewrite?: RuleRewrite): void {
-	const envelope = rule_envelope(outcome, rewrite) ?? foreground_rewrite(outcome, raw_payload)
+	const envelope =
+		foreground_rewrite(outcome, raw_payload, undefined, rewrite) ?? rule_envelope(outcome, rewrite)
 
 	if (envelope === undefined) hook_decision.emit_outcome(outcome)
 	else process.stdout.write(`${envelope}\n`)