@joshuafolkken/kit 1.1128.0 → 1.1166.0

package/scripts/document/entry-read-budget.ts

@@ -57,7 +57,7 @@ const ENTRY_READ_BUDGET: ReadonlyArray<EntryBudget> = [
 	// block in joshuafolkken/kit#2317 when `backlogrun-child.md`'s outage section recorded the
 	// session-resume re-dispatch and the outage-fold window.
 	// Raised in joshuafolkken/kit#2328 when `retrospective.md` joined the point-of-use set and `SKILL.md`
-	// grew by §2j: every entry that reads `SKILL.md` discovers the retrospective document, so its ~5KB
+	// grew by `retrospective.md`: every entry that reads `SKILL.md` discovers the retrospective document, so its ~5KB
 	// and the new section crossed a block for each. The lane child is exempt — it never runs the
 	// retrospective (`run:step` answers `stop` for a child at the stop position), so it skips both.
 	// joshuafolkken/kit#2335 recorded the drain-time firing with the operational detail in
@@ -70,8 +70,8 @@ const ENTRY_READ_BUDGET: ReadonlyArray<EntryBudget> = [
 	// list, so its ~48KB read crossed a block downward and the recorded ceiling drops to the block multiple
 	// the stale-ratchet message named. The other entries still read it, so their rows hold.
 	// joshuafolkken/kit#2345 added the `implementation-unit` delegation row (full fan-out procedure in
-	// `docs/josh-commands-automation.md` → "`josh fanout`"); `SKILL.md` §2b gained only a one-clause mention and a
-	// pointer, folded into the existing enumeration and offset by tightening §2b prose, so every entry
+	// `docs/josh-commands-automation.md` → "`josh fanout`"); `delegation.md` gained only a one-clause mention and a
+	// pointer, folded into the existing enumeration and offset by tightening `delegation.md` prose, so every entry
 	// stayed within its block (kickoff has no block of headroom — its pre-#2294 ceiling is the next
 	// multiple, which the downward ratchet holds shut).
 	// joshuafolkken/kit#2353 wired the watcher-guard note into `backlogrun-progress.md` (read by the three
@@ -92,12 +92,24 @@ const ENTRY_READ_BUDGET: ReadonlyArray<EntryBudget> = [
 	// `backlogrun-*` phase documents it never opens. Each total now counts only what its path reaches.
 	// joshuafolkken/kit#3077 trimmed non-resident rule bodies from `CLAUDE.md`, lowering fullrun, prrun
 	// and backlogrun one block each.
-	{ entry: 'kickoff', bytes: 65_536 },
-	{ entry: 'fullrun', bytes: 126_976 },
-	{ entry: 'halfrun', bytes: 106_496 },
-	{ entry: 'prrun', bytes: 131_072 },
-	{ entry: 'backlogrun', bytes: 212_992 },
-	{ entry: LANE_CHILD, bytes: 77_824 },
+	// Lowered in joshuafolkken/kit#3172: the heartbeat left `backlogrun-progress.md` for its own
+	// `progress-watcher.md`, and `pre-gate-cut.md` became the lane child's alone, so fullrun, halfrun
+	// and prrun stop paying for ~50KB of batch and lane procedure; backlogrun lost the moved prose.
+	// Lowered in joshuafolkken/kit#3174: `SKILL.md` was cut to a manifest (~21KB → ~11KB) and the entry
+	// sequence `fullrun`, `halfrun` and `prrun` shared moved into one `entry-sequence.md`.
+	// Lowered in joshuafolkken/kit#3175: the loop became the driver's hand-backs, the supervisor and
+	// provider prose moved to `docs/josh-commands-automation.md`, and the failure-only sections moved to
+	// `backlogrun-recovery.md`, which the parent's reach still charges whole.
+	// joshuafolkken/kit#3171 cut `CLAUDE.md` to triggers and pointers (~12 KB), lowering every entry.
+	{ entry: 'kickoff', bytes: 45_056 },
+	// Raised in joshuafolkken/kit#3177: #3173, #3181 and #3183 merged in parallel and together tipped
+	// fullrun 12 bytes over its block; none of #3177's documents are in its read set.
+	// Lowered back in joshuafolkken/kit#3180: the history and lint-settled proofs left its read set.
+	{ entry: 'fullrun', bytes: 57_344 },
+	{ entry: 'halfrun', bytes: 57_344 },
+	{ entry: 'prrun', bytes: 61_440 },
+	{ entry: 'backlogrun', bytes: 176_128 },
+	{ entry: LANE_CHILD, bytes: 57_344 },
 ]
 
 function byte_size(root: string, relative_path: string): number {

package/scripts/document/lane-child-read-set.ts

@@ -19,19 +19,12 @@ const LANE_CHILD = 'lane-child'
 const FULLRUN = 'fullrun'
 
 // **The `SKILL.md` sections a dispatched lane child never uses**, read at the section level rather
-// than in full. A child is handed one issue to run, so it never files a new one with an `into`
-// target (§2a), never delegates its own pre-implementation reading (§2b), never names a repository or
-// scouts for a duplicate at its entry (§2c, §2e), returns an observation to the parent rather than
-// filing it (§2i), and never edits these documents (§3). Its dispatch is already an explicit workflow
-// invocation, so §0 cannot decide anything for it either. Review delegation remains in chain-rule.md.
+// than in full. A child never edits these documents (§3), and its dispatch is already an explicit
+// workflow invocation, so §0 cannot decide anything for it either. The other rules it never uses — the
+// `into` target, delegation, the repository prefix, the scout, observation filing, the retrospective —
+// are single rows of §2's table since joshuafolkken/kit#3174, so no section of them is left to trim.
 const UNUSED_SKILL_SECTIONS: ReadonlyArray<string> = [
 	'0. The rule that fires before any of them — explicit invocation',
-	'2a. The `into <target>` suffix — where the new Issue lands',
-	'2b. Delegating a step to a cheaper tier',
-	'2c. The `owner/repo#` prefix — which repository the run acts on',
-	'2e. Before filing a new Issue — `pnpm josh issue:scout`',
-	'2i. An observation worth filing is filed without asking',
-	'2j. The end-of-run retrospective — read when `run:step` prints it',
 	'3. What stays resident, and what is read from here',
 ]
 
@@ -49,10 +42,12 @@ const UNUSED_SKILL_SECTIONS: ReadonlyArray<string> = [
 // list — what one invocation approves, the named-issue order, the session-cut record, the loop and the
 // once-per-session tail — none of which a leaf child performs. Every reference to it lives in a
 // document the child never reads (`backlogrun.md`, `backlogrun-progress.md`, `retrospective.md`) or in a
-// `SKILL.md` section the child trims (§0's session-cut note, §2b, §2i, §2j), so the child has no path
+// `SKILL.md` section the child trims (§0's session-cut note), so the child has no path
 // that opens it. It was the child's single largest read — ~16,000 tokens read whole — charged for a
 // document it never reaches, so dropping it is a correction of an over-count, not a loss of any rule the
 // child needs. The parent still reads it in full.
+// **`progress-watcher.md` is the parent's too** (joshuafolkken/kit#3172): a dispatched child is refused
+// a watcher by its `JOSH_LANE_CHILD` mark, so it never opens the watcher's document.
 const SKIPPED_POINT_OF_USE: ReadonlySet<string> = new Set([
 	'backlogrun-child.md',
 	'backlogrun-lanes.md',
@@ -61,13 +56,16 @@ const SKIPPED_POINT_OF_USE: ReadonlySet<string> = new Set([
 	'delegation.md',
 	'issue-scout.md',
 	'latest-gate.md',
+	'progress-watcher.md',
 	'retrospective.md',
 ])
 
 // **A child that parks reads `backlogrun-park.md`** (`SKILL.md` §1, "A lane child that parks"), a
 // document a standalone `fullrun`'s path never names — so the child's reach adds it to its base
-// entry's (joshuafolkken/kit#3078).
-const REACHED_POINT_OF_USE: ReadonlySet<string> = new Set(['backlogrun-park.md'])
+// entry's (joshuafolkken/kit#3078). **`pre-gate-cut.md` is the child's alone** (joshuafolkken/kit#3172):
+// only a lane child resumes or takes the pre-gate cut, so `fullrun.md` stopped naming it and the
+// child's reach carries it instead.
+const REACHED_POINT_OF_USE: ReadonlySet<string> = new Set(['backlogrun-park.md', 'pre-gate-cut.md'])
 
 function costed(root: string): ReadSetCost {
 	return read_set_trim.costed(root, {

package/scripts/document/read-set-cli.ts

@@ -48,15 +48,15 @@ const POINT_OF_USE_LABEL = '-- read at the point of use, not at the entry --'
 const LANE_CHILD_NOTE: ReadonlyArray<string> = [
 	'  a dispatched lane child (`JOSH_LANE_CHILD`) reads this trimmed set:',
 	'  - skips the point-of-use documents the parent owns — child dispatch, lane opening, the progress watcher and the hand-off',
-	'  - omits SKILL.md §0/§2a/§2b/§2c/§2e/§2i/§3 — dispatch already authorized the run and a leaf child never uses them',
+	'  - omits SKILL.md §0/§3 — dispatch already authorized the run and a leaf child edits no rule',
 ]
 // **The `backlogrun` parent reads a trimmed set of its own** — a scheduler that never implements, so
 // the implementer-only `SKILL.md` sections are read section by section rather than whole
-// (joshuafolkken/kit#2256). A *different* trim from the lane child's: the parent keeps §0/§2b/§2c/§2e/
-// §2i, which are the scheduler's own, and drops no point-of-use document.
+// (joshuafolkken/kit#2256). A *different* trim from the lane child's: the parent keeps §0, which is the
+// scheduler's own, and drops no point-of-use document.
 const BACKLOGRUN_PARENT_NOTE: ReadonlyArray<string> = [
 	'  the backlogrun parent (scheduler) reads this trimmed set:',
-	'  - omits SKILL.md §2a/§2f/§2g/§3 — the parent never implements, so it claims no tree and files no `into` target',
+	'  - omits SKILL.md §3 — the parent edits no rule mid-run',
 	'  - keeps every point-of-use document — the parent is the one dispatching children and running lanes',
 ]
 const FETCH_RULE =

package/scripts/document/read-set-point-of-use.ts

@@ -15,7 +15,7 @@
 // is joshuafolkken/kit#1856's addition**: it governs the `/code-review` → `followup` chain, which in
 // `fullrun` / `queue` / `epicrun` / `backlogrun` runs *after* the first edit, so its 7,396 tokens
 // were resident from the entry for no run that had yet reached a review.
-// **`background-commands.md` is joshuafolkken/kit#1873's**: it was §2h's resident body, governing the
+// **`background-commands.md` is joshuafolkken/kit#1873's**: it was `background-commands.md`'s resident body, governing the
 // background execution of the gate, the push and the merge tail — all after the first edit — so it
 // left `SKILL.md` for the point-of-use list. `SKILL.md` → §1, "Four documents are read at the point
 // of use", is the single source.
@@ -32,18 +32,26 @@
 // cut, a step every implementing run — and every dispatched lane child — reaches after the entry, so
 // its read is a point-of-use read the count was silently omitting. Measured on the backlogrun of
 // 2026-09-21, the lane children read it 21 times across 13 runs — the largest single document read,
-// and the one the point-of-use list had no row for.
+// and the one the point-of-use list had no row for. Only a lane child reaches it (joshuafolkken/kit#3172):
+// `fullrun.md` no longer names it, so it is charged to the lane child's role alone.
+// **`progress-watcher.md` joins them** (joshuafolkken/kit#3172): the heartbeat every implementing run
+// starts once its hold is claimed, split out of `backlogrun-progress.md` so a single-issue run stops
+// paying for the batch's hand-off and waiting procedure to read it.
 const POINT_OF_USE_FILES: ReadonlySet<string> = new Set([
 	'latest-gate.md',
 	'followup.md',
 	'chain-rule.md',
 	'background-commands.md',
 	'pre-gate-cut.md',
+	'progress-watcher.md',
 	'backlogrun-child.md',
 	'backlogrun-lanes.md',
 	'backlogrun-progress.md',
 	'backlogrun-park.md',
 	'backlogrun-steps.md',
+	// Read only when a delegated unit goes silent or a lane's pull request conflicts with `main` — a
+	// failure path, so a run in which nothing fails never reads it (joshuafolkken/kit#3175).
+	'backlogrun-recovery.md',
 	// Read only when `run:step` prints `pnpm josh retrospective` at a run's stop position — the very
 	// end of a run, never the entry (joshuafolkken/kit#2328). Kept out of every entry's read for the
 	// same reason the phase documents above are: no run that never drains its backlog reaches it.

package/scripts/document/resident-budget.ts

@@ -0,0 +1,47 @@
+import { document_reachability } from './document-reachability'
+
+// The byte budget of the always-resident document — `CLAUDE.md`, loaded on every request. It is held
+// here rather than in `document-byte-budget.ts` because a resident document is covered by every entry
+// total and must not carry a per-document block entry as well (joshuafolkken/kit#2257); it is held here
+// rather than inside `workflow-skills.test.ts` so `josh bytes CLAUDE.md` counts against the same number
+// the suite enforces (joshuafolkken/kit#3171). Loosening any of the three constants is Tier C —
+// `prompts/collaboration-workflow/residency.md`.
+
+// The documents sat at ~83 KB each before the joshuafolkken/kit#854 split, crept back to ~56 KB, and
+// were cut below 30 KB by joshuafolkken/kit#1924. joshuafolkken/kit#3171 cut `CLAUDE.md` to ~14 KB —
+// triggers and pointers only — and lowered this ceiling with it, so the document cannot creep back. It
+// is a guard against re-inlining, not a budget to tune prose against.
+const RESIDENT_CEILING_BYTES = 18_000
+
+// joshuafolkken/kit#951: the ceiling alone stops the wrong thing. Reached, it does not block the
+// next rule — it makes that rule pay for itself by deleting a neighboring sentence, and the
+// sentence chosen is whichever one no marker pinned rather than whichever one matters least. A
+// required margin turns "at the limit" into a failure while there is still room to write the fix,
+// which is the only point at which moving a procedure into a skill is still a choice.
+const RESIDENT_HEADROOM_BYTES = 2000
+
+// joshuafolkken/kit#1275: a floor under the room left once the procedures are out, so a wholesale
+// re-inlining fails by name instead of silently returning the document to a few bytes of headroom.
+const RE_INLINE_GUARD_HEADROOM_BYTES = 1000
+
+const EFFECTIVE_CEILING_BYTES = RESIDENT_CEILING_BYTES - RESIDENT_HEADROOM_BYTES
+
+// The size a resident document must stay below — the effective ceiling minus the re-inline floor. The
+// suite fails at it, and `josh bytes` counts the headroom against it.
+const RESIDENT_LIMIT_BYTES = EFFECTIVE_CEILING_BYTES - RE_INLINE_GUARD_HEADROOM_BYTES
+
+// The limit for a resident document, or undefined for any other path.
+function limit_bytes_for(relative_path: string): number | undefined {
+	return document_reachability.RESIDENT_BASE.includes(relative_path)
+		? RESIDENT_LIMIT_BYTES
+		: undefined
+}
+
+const resident_budget = {
+	EFFECTIVE_CEILING_BYTES,
+	RE_INLINE_GUARD_HEADROOM_BYTES,
+	RESIDENT_LIMIT_BYTES,
+	limit_bytes_for,
+}
+
+export { resident_budget }

package/scripts/epic/epic-shape.ts

@@ -5,7 +5,7 @@ import { to_issue_reference } from './epic-reference'
 // Whether an issue is an epic this repository's writers may edit, and why it is not when it is not.
 //
 // Both `josh epic --add` and `josh epic --remove` ask exactly this before they compute anything: the
-// label, the absence of a cross-repository child, a task list to place rows in, and a declaration
+// label, a task list to place rows in, and a declaration
 // their edit can be relative to. It lives in one module rather than in each of them, because the two
 // commands must refuse the same inputs for the same reasons — a second copy is where one comes to
 // accept an epic the other refuses (joshuafolkken/kit#1712).
@@ -40,18 +40,15 @@ function promote_remedy(epic_number: number): string {
 // The label and the task list are checked separately from the declaration because they fail
 // differently: without rows there is nowhere to put a new one, and without a declaration there is
 // nothing for an edit to be relative to.
-function find_epic_shape_error(subject: EpicShapeSubject, body: string): string | undefined {
-	const reference = to_issue_reference(subject.epic_number)
-
-	if (!subject.labels.includes(EPIC_LABEL)) {
-		return `${reference} does not carry the \`${EPIC_LABEL}\` label, so it is not an epic. ${promote_remedy(subject.epic_number)}`
-	}
-
-	if (epic_parse.has_external_task_list_entry(body)) {
-		return `${reference} tracks a child in another repository; editing the declared order of a cross-repository epic is joshuafolkken/kit#864's scope, not this command's.`
-	}
+//
+// **A child in another repository is not a refusal** (joshuafolkken/kit#3161). The declaration names
+// bare numbers only, so neither command can write an order across repositories — such an order lives
+// in the native relations alone (`epic_graph.child_links`), which these edits never read or drop — and
+// the rewrite leaves a row it does not recognize exactly where it stood.
+function find_epic_shape_error(subject: EpicShapeSubject): string | undefined {
+	if (subject.labels.includes(EPIC_LABEL)) return undefined
 
-	return undefined
+	return `${to_issue_reference(subject.epic_number)} does not carry the \`${EPIC_LABEL}\` label, so it is not an epic. ${promote_remedy(subject.epic_number)}`
 }
 
 function find_subject_error(
@@ -60,7 +57,7 @@ function find_subject_error(
 ): string | undefined {
 	const reference = to_issue_reference(subject.epic_number)
 	if (subject.body === undefined) return `Could not read the body of ${reference}.`
-	const shape_error = find_epic_shape_error(subject, subject.body)
+	const shape_error = find_epic_shape_error(subject)
 	if (shape_error !== undefined) return shape_error
 
 	if (tracked.length === 0) {

package/scripts/epic/epic-solo.ts

@@ -6,7 +6,7 @@ import { epic_report, type EpicNextResult } from './epic-report'
 
 // The `run:solo` gate on what a run is offered (joshuafolkken/kit#2776).
 //
-// `wip-cap.md`'s run-alone section says an issue whose defect reaches the verification path runs
+// `backlogrun-lanes.md`'s run-alone rule says an issue whose defect reaches the verification path runs
 // alone, and until this gate that was a judgement made at dispatch — the offer handed such an issue
 // out beside others and `backlog:drive` launched every number it was given. The label records the
 // judgement once; this applies it to every ask, so it holds without an agent in the loop.

package/scripts/exports/unused-members-cli.ts

@@ -9,7 +9,11 @@ const CHECK = 'exports'
 const FAIL_EXIT_CODE = 1
 // A consumer's namespaces are read from `.svelte` files and routes a TypeScript program over its
 // `tsconfig.json` does not see, so every member they use would read as unused. The check is kit's own.
-const CONSUMER_SKIP_REASON = 'checks only the kit repository itself, not a consumer project'
+//
+// **Not a skip notice** (joshuafolkken/kit#3162). `SKIP_MARKER` means "a check passed without running",
+// and the gate withholds its green record on it — so a consumer, where this notice prints on every
+// run, never got a green record. Out of scope by design is not unverified, so the marker stays out.
+const CONSUMER_NOTICE = `josh ${CHECK}: checks only the kit repository itself — nothing to check in a consumer project.`
 
 function format_member(root: string, member: NamespaceMember): string {
 	return `${path.relative(root, member.file)}:${String(member.line)}  ${member.namespace}.${member.member}`
@@ -26,7 +30,7 @@ function report(root: string, members: ReadonlyArray<NamespaceMember>): string {
 
 async function run_unused_members(root: string): Promise<number> {
 	if (doctor_consumer.is_kit_consumer(root)) {
-		console.info(project_checks.skip_notice(CHECK, CONSUMER_SKIP_REASON))
+		console.info(CONSUMER_NOTICE)
 
 		return 0
 	}
@@ -48,6 +52,6 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
 	process.exitCode = await run_unused_members(project_checks.project_root(process.cwd()))
 }
 
-const unused_members_cli = { run_unused_members }
+const unused_members_cli = { run_unused_members, CONSUMER_NOTICE }
 
 export { unused_members_cli }

package/scripts/gate/scoped-green.ts

@@ -2,6 +2,7 @@ import { file_map_stamp, type FileMapStampAccess } from '#scripts/josh/file-map-
 import { hook_decision } from '#scripts/josh/hook-decision'
 import { review_brief } from '#scripts/review/review-brief'
 import { review_stamps } from '#scripts/review/review-stamps'
+import { test_unit_guard } from '#scripts/test/test-unit-guard'
 import { gate_tree, type GateTree } from './gate-tree'
 
 // Whether the two scoped checks have been green on *this exact tree* by the time the review is
@@ -60,26 +61,36 @@ interface ScopedCheck {
 
 // The record paths, overridable so a test can plant one without overwriting the record a real run in
 // this checkout relies on — the same reason `gate_skip.reusable_green_gate` takes a `source`.
+// `is_unit_skipped` is overridable for the same reason, so a suite running in a checkout with vitest
+// can stand in for a project without one.
 interface ScopedSources {
 	lint?: string
 	test?: string
+	is_unit_skipped?: boolean
 }
 
+// **`test:related` is required only where it can ever answer** (joshuafolkken/kit#3136). In a project
+// whose unit guard skips — vitest absent, or a basic project with no test file — `test:related` runs
+// nothing and so writes no record, and requiring one refused the gate forever with no way through.
+// The guard's own decision is asked rather than re-derived, so the writer and this reader agree; a
+// project with a unit suite still needs the record, and a run that executed nothing still writes none.
 function checks_of(sources: ScopedSources): ReadonlyArray<ScopedCheck> {
-	return [
-		{
-			script: LINT_SCRIPT,
-			command: LINT_COMMAND,
-			stamp: review_stamps.lint_related_stamp,
-			source: sources.lint,
-		},
-		{
-			script: TEST_SCRIPT,
-			command: TEST_COMMAND,
-			stamp: review_stamps.test_related_stamp,
-			source: sources.test,
-		},
-	]
+	const lint = {
+		script: LINT_SCRIPT,
+		command: LINT_COMMAND,
+		stamp: review_stamps.lint_related_stamp,
+		source: sources.lint,
+	}
+	const test = {
+		script: TEST_SCRIPT,
+		command: TEST_COMMAND,
+		stamp: review_stamps.test_related_stamp,
+		source: sources.test,
+	}
+
+	return (sources.is_unit_skipped ?? test_unit_guard.is_skipping(process.cwd()))
+		? [lint]
+		: [lint, test]
 }
 
 // **An unreadable record reads as an absent one, and that is the safe direction.** `read` swallows a

package/scripts/gh/git-gh-api-path.ts

@@ -97,10 +97,17 @@ function tag_reference_api_path(tag: string, repo?: string): string {
 	return `${repo_api_path(repo)}/git/ref/tags/${tag}`
 }
 
+// The GitHub Release published for one tag. REST answers 404 until `publish.yml`'s `create-release`
+// job has run, which is what the release command's progress watch asks (joshuafolkken/kit#3193).
+function release_by_tag_api_path(tag: string, repo?: string): string {
+	return `${repo_api_path(repo)}/releases/tags/${tag}`
+}
+
 const git_gh_api_path = {
 	FULL_PAGE_QUERY,
 	repo_api_path,
 	tag_ref_api_path: tag_reference_api_path,
+	release_by_tag_api_path,
 	issues_api_path,
 	issue_api_path,
 	blocked_by_api_path,

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

@@ -2,7 +2,7 @@
 import { text } from 'node:stream/consumers'
 import { fileURLToPath } from 'node:url'
 import { hook_decision } from '#scripts/josh/hook-decision'
-import { pretool_outcome_async } from './pretool-guard'
+import { pretool_guard, pretool_outcome_async } from './pretool-guard'
 
 // The `PreToolUse` hook's entry, kept apart from the composition in `pretool-guard.ts`
 // (joshuafolkken/kit#2922). The hook bundles are built with `splitting: true`, which moves a module
@@ -16,6 +16,6 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
 		const raw_payload = await text(process.stdin)
 
 		hook_decision.load_environment_file()
-		hook_decision.emit_outcome(await pretool_outcome_async(raw_payload))
+		pretool_guard.emit(raw_payload, await pretool_outcome_async(raw_payload))
 	}
 }

package/scripts/hooks/pretool-guard.ts

@@ -1,9 +1,11 @@
 import { duplicate_read_outcome } from '#scripts/delegation/duplicate-read-guard'
 import { investigation_refusal } from '#scripts/delegation/investigation-guard'
-import type { GuardOutcome } from '#scripts/josh/hook-decision'
+import { hook_decision, type GuardOutcome } from '#scripts/josh/hook-decision'
 import { delivered_rules } from '#scripts/rules/delivered-rules'
+import { lane_background } from '#scripts/rules/lane-background'
 import { run_parent_cut_hook } from '#scripts/run/run-parent-cut-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 { step_zero_notice } from './step-zero-notice'
 
@@ -108,6 +110,47 @@ async function pretool_outcome_async(raw_payload: string): Promise<GuardOutcome>
 	return with_step_zero_notice(base, raw_payload)
 }
 
-const pretool_guard = { combine_outcomes, pretool_outcome }
+function guarded_call(raw_payload: string): GuardedCall | undefined {
+	try {
+		const payload = hook_decision.parse_hook_payload(raw_payload)
+
+		return payload === undefined
+			? undefined
+			: { name: payload.tool_name, input: payload.tool_input }
+	} catch {
+		return undefined
+	}
+}
+
+// The envelope that replaces the outcome's own when a lane child backgrounded `josh ship` alone
+// (joshuafolkken/kit#3154): 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_rewrite(
+	outcome: GuardOutcome,
+	raw_payload: string,
+	is_lane_child?: () => boolean,
+): 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)
+
+	if (input === undefined) return undefined
+
+	const context = [lane_background.FOREGROUND_NOTE, outcome.notice ?? outcome.fault]
+
+	return hook_decision.rewrite_envelope(input, context.filter(Boolean).join('\n\n'))
+}
+
+// The hook's one write: the foreground rewrite where it applies, the outcome's own envelope otherwise.
+function emit(raw_payload: string, outcome: GuardOutcome): void {
+	const rewrite = foreground_rewrite(outcome, raw_payload)
+
+	if (rewrite === undefined) hook_decision.emit_outcome(outcome)
+	else process.stdout.write(`${rewrite}\n`)
+}
+
+const pretool_guard = { combine_outcomes, emit, foreground_rewrite, pretool_outcome }
 
 export { pretool_guard, pretool_outcome, pretool_outcome_async }

package/scripts/hooks/run-hook.sh

@@ -0,0 +1,41 @@
+#!/bin/sh
+# Launch one kit hook by name: `sh scripts/hooks/run-hook.sh <name> [arguments...]`
+# (joshuafolkken/kit#3184).
+#
+# A hook command in `.claude/settings.json` / `.codex/hooks.json` only moves to the project root
+# (`scripts/init/hook-launch.ts`) and calls this script, so everything every hook shares lives here once:
+#
+# - The git location variables a git hook exports are cleared when the root resolves without them, so
+#   the hook's own git calls act on the checkout it stands in. They are kept when the checkout needs
+#   them — git metadata outside the work tree.
+# - The pre-built bundle `dist/hooks/<name>.js` runs once its gate passes; otherwise the live source
+#   runs through josh, whose command is the name with its first `-` turned into `:`
+#   (`pretool-guard` → `pretool:guard`).
+# - In kit's own checkout the gate is `hook-bundle-ready.ts`, which rebuilds stale bundles
+#   (joshuafolkken/kit#2984). In an installed package it is a presence check: the published bundles
+#   cannot be stale against a source the consumer never edits, and Node strips no types under
+#   `node_modules`.
+# - An `if`/`else`, never `&&`/`||`: a guard's refusal is a non-zero exit, and a chain would read it as
+#   a missing bundle and run the hook twice.
+
+location_variables='GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_DIR GIT_INDEX_FILE GIT_NAMESPACE GIT_OBJECT_DIRECTORY GIT_WORK_TREE'
+unset_options=''
+for variable in $location_variables; do unset_options="$unset_options -u $variable"; done
+# shellcheck disable=SC2086
+if env $unset_options git rev-parse --show-toplevel >/dev/null 2>&1; then unset $location_variables; fi
+
+hook_name=$1
+shift
+hooks_dir=$(dirname "$0")
+package_dir="$hooks_dir/../.."
+bundle="$package_dir/dist/hooks/$hook_name.js"
+josh_command="${hook_name%%-*}:${hook_name#*-}"
+
+case $0 in
+*node_modules/*)
+	if [ -d "$package_dir/dist/hooks" ]; then node "$bundle" "$@"; else node "$package_dir/dist/josh.js" "$josh_command" "$@"; fi
+	;;
+*)
+	if node --disable-warning=ExperimentalWarning "$hooks_dir/hook-bundle-ready.ts"; then node "$bundle" "$@"; else pnpm josh "$josh_command" "$@"; fi
+	;;
+esac

package/scripts/init/claude-kit-only-settings.ts

@@ -0,0 +1,29 @@
+import { patch_json_key } from '#scripts/config-merge/patch-json-key'
+import { claude_plugin_config } from './claude-plugin-config'
+
+// Keys kit's own `.claude/settings.json` sets for its sessions but never ships. `enableArtifact:
+// false` keeps the Artifact tool's ~12k tokens out of every call of a kit run
+// (joshuafolkken/kit#3140), but Claude Code lets any layer that sets it to `false` win, so a
+// consumer given it could not turn the tool back on from `.claude/settings.local.json`.
+const KIT_ONLY_SETTING_KEYS: ReadonlyArray<string> = ['enableArtifact']
+
+function strip_kit_only_settings(content: string): string {
+	let stripped = content
+	for (const key of KIT_ONLY_SETTING_KEYS) stripped = patch_json_key.remove_json_key(stripped, key)
+
+	return stripped
+}
+
+function apply_kit_only_strip_for_destination(destination_path: string, content: string): string {
+	return destination_path.endsWith(claude_plugin_config.CLAUDE_SETTINGS_DESTINATION)
+		? strip_kit_only_settings(content)
+		: content
+}
+
+const claude_kit_only_settings = {
+	KIT_ONLY_SETTING_KEYS,
+	strip_kit_only_settings,
+	apply_kit_only_strip_for_destination,
+}
+
+export { claude_kit_only_settings }

package/scripts/init/hook-command-rewrite.ts

@@ -3,60 +3,43 @@ import { hook_launch } from './hook-launch'
 
 // The consumer's `.claude/settings.json` runs its hooks off the published package directly, not
 // through `pnpm josh` (joshuafolkken/kit#1930, joshuafolkken/kit#2023). Two paths inside a hook
-// command are rebased onto the installed package: the per-hook bundle `dist/hooks/<name>.js` a hook
-// prefers, and the `pnpm josh <command>` fallback it drops to when that bundle is missing — which for
-// a consumer becomes the `dist/josh.js` dispatcher, since the published package always ships `dist`
-// and a `pnpm` launch would only add the wrapper this exists to remove.
+// command are rebased onto the installed package: the hook launcher `scripts/hooks/run-hook.sh`
+// (joshuafolkken/kit#3184), which picks the bundle or the dispatcher from where it is installed, and a
+// plain `pnpm josh <command>`, which becomes the `dist/josh.js` dispatcher — the published package
+// always ships `dist`, and a `pnpm` launch would only add the wrapper this exists to remove.
 //
-// kit's own settings file keeps the `pnpm josh` fallback (`tsx scripts/josh/josh.ts` against live
-// source), so a fresh clone with no `dist/` still runs the current guards. The rewrite is gated on the
-// copy destination, exactly as the plugin injection is — kit's source tree is never transformed in
-// place.
+// kit's own settings file keeps the launcher's live-source fallback (`pnpm josh` against
+// `scripts/josh/josh.ts`), so a fresh clone with no `dist/` still runs the current guards. The rewrite
+// is gated on the copy destination, exactly as the plugin injection is — kit's source tree is never
+// transformed in place.
 
 const PNPM_JOSH_PREFIX = 'pnpm josh '
-const CODEX_ADAPTER_SOURCE = 'pnpm exec tsx scripts/hooks/codex-hook-adapter.ts'
 // Relative to the consumer's project root, which hook commands select before using this path.
 // The path is the plugin marketplace's `node_modules` location plus the built entry `bin.josh` names.
 const BUNDLE_INVOCATION = `node ${claude_plugin_config.MARKETPLACE_PATH}/dist/josh.js `
-// The per-hook bundle directory a fresh clone builds, and where it lives inside the installed package.
-const HOOK_BUNDLE_DIR = `${hook_launch.HOOK_DIST_DIR}/`
-const CONSUMER_HOOK_BUNDLE_DIR = `${claude_plugin_config.MARKETPLACE_PATH}/${HOOK_BUNDLE_DIR}`
+// Anchored on the `sh ` that launches it: the installed path still ends in the source path, so only the
+// anchor keeps a second pass from rebasing an already-rebased launcher onto itself.
+const RUN_HOOK_INVOCATION = `sh ${hook_launch.RUN_HOOK_SCRIPT} `
+const CONSUMER_RUN_HOOK_INVOCATION = `sh ${claude_plugin_config.MARKETPLACE_PATH}/${hook_launch.RUN_HOOK_SCRIPT} `
 const CONSUMER_PACKAGE_MANIFEST = `${claude_plugin_config.MARKETPLACE_PATH}/package.json`
 const MISSING_INSTALL_NOTICE = 'kit hooks inactive: run pnpm install, then reread CLAUDE.md'
 const MISSING_INSTALL_GUARD = `if [ ! -f ${CONSUMER_PACKAGE_MANIFEST} ]; then echo '${MISSING_INSTALL_NOTICE}' >&2; exit 0; fi; `
-const CODEX_ADAPTER_BUNDLE = `node ${CONSUMER_HOOK_BUNDLE_DIR}codex-hook-adapter.js`
 const CODEX_HOOKS_DESTINATION = '.codex/hooks.json'
 // The values below are matched inside raw JSON text, so the root prefix is taken in its escaped form.
 const PROJECT_ROOT_PREFIX = JSON.stringify(hook_launch.PROJECT_ROOT_PREFIX).slice(1, -1)
-// The installed package ships its bundles built, so they cannot be stale against a source the consumer
-// never has: the ready gate kit's own commands pass (joshuafolkken/kit#2984) becomes a presence check.
-const CONSUMER_READY_GATE = `[ -d ${CONSUMER_HOOK_BUNDLE_DIR} ]`
 // Capture the value of every `"command"` field, escapes and all, so the rewrites below touch command
 // values alone — never an echo reminder's prose or a `"description"` that merely mentions the string.
 const COMMAND_FIELD = /("command":\s*")((?:[^"\\]|\\.)*)(")/gu
 
-// Idempotent on its own: `CONSUMER_HOOK_BUNDLE_DIR` still contains `HOOK_BUNDLE_DIR`, so a blind
-// second pass would rebase an already-rebased path onto itself. A value already targeting the
-// installed package is left untouched, restoring the idempotency the earlier `pnpm josh`-anchored
-// rewrite had for free.
-function rebase_bundle_directory(value: string): string {
-	return value.includes(CONSUMER_HOOK_BUNDLE_DIR)
-		? value
-		: value.split(HOOK_BUNDLE_DIR).join(CONSUMER_HOOK_BUNDLE_DIR)
-}
-
-// Rebase both paths a hook command can carry: the bundle it prefers, then the `pnpm josh` fallback.
-// The bundle rewrite runs first — its replacement never contains `pnpm josh`, so the two are
-// independent whichever order they run. The fallback rewrite is idempotent too (`BUNDLE_INVOCATION`
-// holds no `pnpm josh `), so the whole rewrite is safe to run more than once.
+// Rebase both paths a hook command can carry: the launcher, then a plain `pnpm josh`. Neither
+// replacement contains the other's anchor, so the two are independent whichever order they run, and
+// the whole rewrite is safe to run more than once.
 function rewrite_command_value(value: string): string {
-	const rewritten = rebase_bundle_directory(value)
-		.split(hook_launch.BUNDLE_READY_GATE)
-		.join(CONSUMER_READY_GATE)
+	const rewritten = value
+		.split(RUN_HOOK_INVOCATION)
+		.join(CONSUMER_RUN_HOOK_INVOCATION)
 		.split(PNPM_JOSH_PREFIX)
 		.join(BUNDLE_INVOCATION)
-		.split(CODEX_ADAPTER_SOURCE)
-		.join(CODEX_ADAPTER_BUNDLE)
 
 	if (!rewritten.includes(claude_plugin_config.MARKETPLACE_PATH)) return rewritten
 	if (rewritten.includes(MISSING_INSTALL_GUARD)) return rewritten