@joshuafolkken/kit 1.1136.0 → 1.1166.0

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/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/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

package/scripts/init/hook-launch.ts

@@ -7,51 +7,40 @@ import { GIT_LOCATION_VARIABLES } from '#scripts/git/git-location-environment'
 //
 // **The command starts from the project root, never from wherever the session happens to be**
 // (joshuafolkken/kit#2984). Every path after the prefix is relative, so a hook fired from a
-// subdirectory would otherwise miss its bundle. The root is git's, with the location variables a git
-// hook exports cleared first — the same resolution the consumer rewrite (`hook-command-rewrite.ts`)
-// applies, so both sides stay one mechanism for Claude Code and Codex alike.
+// subdirectory would otherwise miss its script. The root is git's, resolved with the location
+// variables a git hook exports cleared first, and resolved with them only when that fails — git
+// metadata outside the work tree. The consumer rewrite (`hook-command-rewrite.ts`) keeps this prefix,
+// so both sides stay one mechanism for Claude Code and Codex alike.
 //
-// **The bundle runs only once the ready gate passes** (`scripts/hooks/hook-bundle-ready.ts`): it
-// rebuilds `dist/hooks/` when the source beside it has changed, so an edited guard is never shadowed by
-// its old bundle. The gate failing — a checkout that cannot build — drops to the fallback, the live
-// source. **An `if`/`else`, never `&&`/`||`**: a guard's refusal is a non-zero exit, and a
-// `node … || pnpm josh …` chain would read that refusal as a missing bundle and run the hook twice.
+// **Everything after the root is one script** (`scripts/hooks/run-hook.sh`, joshuafolkken/kit#3184):
+// clearing the location variables for the hook itself, the bundle-ready gate and the live-source
+// fallback live there once, so each hook command names only its hook.
 
 const HOOK_DIST_DIR = 'dist/hooks'
+const RUN_HOOK_SCRIPT = 'scripts/hooks/run-hook.sh'
 const UNSET_OPTIONS = GIT_LOCATION_VARIABLES.map((name) => `-u ${name}`).join(' ')
-const PROJECT_ROOT_PREFIX = `if project_root="$(env ${UNSET_OPTIONS} git rev-parse --show-toplevel 2>/dev/null)"; then unset ${GIT_LOCATION_VARIABLES.join(' ')}; else project_root="$(git rev-parse --show-toplevel)" || exit 1; fi; cd "$project_root" && `
-// Plain `node` runs the gate's TypeScript directly; the flag keeps Node 22's type-stripping notice off
-// every hook's stderr.
-const BUNDLE_READY_GATE =
-	'node --disable-warning=ExperimentalWarning scripts/hooks/hook-bundle-ready.ts'
+const ROOT_LOOKUP = 'git rev-parse --show-toplevel'
+const PROJECT_ROOT_PREFIX = `project_root="$(env ${UNSET_OPTIONS} ${ROOT_LOOKUP} 2>/dev/null || ${ROOT_LOOKUP})" && cd "$project_root" && `
 
-// Run `primary_command` when `gate` exits 0, else `fallback_command` — both verbatim. Kept generic so
-// a test can exercise the branch selection with stub commands rather than real hooks.
-function launch_command(gate: string, primary_command: string, fallback_command: string): string {
-	return `if ${gate}; then ${primary_command}; else ${fallback_command}; fi`
+// `name` is the hook's bundle under `dist/hooks` without `.js` (e.g. `pretool-guard`), followed by any
+// arguments it takes (e.g. `codex-hook-adapter pretool`).
+function hook_launch_command(name: string): string {
+	return `${PROJECT_ROOT_PREFIX}sh ${RUN_HOOK_SCRIPT} ${name}`
 }
 
-// `invocation` is the hook's file under `dist/hooks` plus any arguments (e.g. `pretool-guard.js`);
-// `fallback_command` runs the same hook from source.
-function bundle_launch_command(invocation: string, fallback_command: string): string {
-	const primary = `node ${HOOK_DIST_DIR}/${invocation}`
-
-	return `${PROJECT_ROOT_PREFIX}${launch_command(BUNDLE_READY_GATE, primary, fallback_command)}`
-}
-
-// `bundle` is the hook's file under `dist/hooks` (e.g. `pretool-guard.js`); `command` is the josh
-// subcommand the fallback runs (e.g. `pretool:guard`).
-function hook_launch_command(bundle: string, command: string): string {
-	return bundle_launch_command(bundle, `pnpm josh ${command}`)
+// The josh subcommand the launcher falls back to for hook `name`: its first `-` becomes `:`
+// (`pretool-guard` → `pretool:guard`). The launcher derives it in shell; this is that rule for the tests
+// that hold every wired hook to a subcommand josh has.
+function fallback_command(name: string): string {
+	return name.replace('-', ':')
 }
 
 const hook_launch = {
-	BUNDLE_READY_GATE,
-	bundle_launch_command,
+	fallback_command,
 	HOOK_DIST_DIR,
 	hook_launch_command,
-	launch_command,
 	PROJECT_ROOT_PREFIX,
+	RUN_HOOK_SCRIPT,
 }
 
 export { hook_launch }

package/scripts/issue/issue-auto-ok.ts

@@ -0,0 +1,95 @@
+import { git_branch } from '#scripts/git/git-branch'
+import { git_command } from '#scripts/git/git-command'
+import { run_carry } from '#scripts/run/run-carry'
+import { issue_file } from './issue-file'
+import { AUTO_OK_LABEL, has_label_name } from './issue-labels'
+import { issue_state_cli } from './issue-state-cli'
+
+// Whether `josh issue:file` applies `auto-ok` to the Issue it files (joshuafolkken/kit#3213). Work
+// found during an unattended run used to wait in the backlog until a person labelled it, so the
+// filing now computes the answer instead of leaving it to the agent's memory: an Issue filed while a
+// `backlogrun` carry record is live, or from a branch whose Issue carries `auto-ok`, is opted in by
+// default. `--no-auto-ok` is the one exception, declared for an Issue that needs a person's judgement
+// (a Tier B toss-up or a Tier C action). A filing to another repository is never opted in: that
+// repository's own `backlogrun` would implement and merge it though nobody opted that repository in.
+
+interface AutoOkSignals {
+	is_opted_out: boolean
+	is_carried: boolean
+	// The labels of the Issue the current branch names; `undefined` when the branch names none or the
+	// Issue could not be read.
+	branch_labels: ReadonlyArray<string> | undefined
+}
+
+interface AutoOkDecision {
+	is_applied: boolean
+	reason: string
+}
+
+const OPTED_OUT: AutoOkDecision = { is_applied: false, reason: '--no-auto-ok declared' }
+const CROSS_REPOSITORY: AutoOkDecision = {
+	is_applied: false,
+	reason: 'the Issue is filed to another repository',
+}
+const CARRIED: AutoOkDecision = { is_applied: true, reason: 'a backlogrun carry record is live' }
+const BRANCH_OPTED_IN: AutoOkDecision = {
+	is_applied: true,
+	reason: 'the Issue this branch works on carries auto-ok',
+}
+const NOT_OPTED_IN: AutoOkDecision = {
+	is_applied: false,
+	reason: 'no backlogrun carry record is live and the branch names no auto-ok Issue',
+}
+
+// The opt-out wins over every signal, then the carry record, then the branch's Issue.
+function decide(signals: AutoOkSignals): AutoOkDecision {
+	if (signals.is_opted_out) return OPTED_OUT
+	if (signals.is_carried) return CARRIED
+	if (has_label_name(signals.branch_labels ?? [], AUTO_OK_LABEL)) return BRANCH_OPTED_IN
+
+	return NOT_OPTED_IN
+}
+
+function line_of(decision: AutoOkDecision): string {
+	return `auto-ok: ${decision.is_applied ? 'applied' : 'not applied'} — ${decision.reason}`
+}
+
+// Read from the common git directory, so a lane sees the record its batch wrote in the main tree.
+async function is_carried(): Promise<boolean> {
+	const directory = await run_carry.repository_directory()
+
+	if (directory === undefined) return false
+
+	return run_carry.read_carry(run_carry.carry_path(directory)).kind === 'carried'
+}
+
+// An unreadable Issue is read as no labels: the filing goes on without `auto-ok` rather than failing.
+// The branch names an Issue of `current`, read there by name: a filing to another repository has
+// already pointed `GH_REPO` at its target, which would otherwise answer with the target's Issue.
+async function branch_labels(current: string): Promise<ReadonlyArray<string> | undefined> {
+	const issue_number = git_branch.issue_from_branch(await git_command.branch())
+
+	if (issue_number === undefined) return undefined
+	const read = await issue_state_cli.read_issue(String(issue_number), current)
+
+	return read.kind === 'state' ? read.state.labels : undefined
+}
+
+// Each read is skipped once an earlier signal has already decided the answer; a cross-repository
+// filing is refused before any signal is read.
+async function resolve(
+	is_opted_out: boolean,
+	target: string,
+	current: string,
+): Promise<AutoOkDecision> {
+	if (is_opted_out) return OPTED_OUT
+	if (!issue_file.is_same_repository(target, current)) return CROSS_REPOSITORY
+	if (await is_carried()) return CARRIED
+
+	return decide({ is_opted_out, is_carried: false, branch_labels: await branch_labels(current) })
+}
+
+const issue_auto_ok = { decide, line_of, resolve }
+
+export type { AutoOkDecision, AutoOkSignals }
+export { issue_auto_ok }