@joshuafolkken/kit 1.1035.0 → 1.1094.0

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

@@ -0,0 +1,21 @@
+#!/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_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
+// imported by two entries into a shared chunk — and `codex-hook-adapter.ts` imports `pretool-guard.ts`.
+// Its self-invoke went into that chunk, whose `import.meta.url` never equals the launched
+// `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()
+		hook_decision.emit_outcome(await pretool_outcome_async(raw_payload))
+	}
+}

package/scripts/hooks/pretool-guard.ts

@@ -1,12 +1,11 @@
-#!/usr/bin/env tsx
-import { text } from 'node:stream/consumers'
-import { fileURLToPath } from 'node:url'
 import { duplicate_read_outcome } from '#scripts/delegation/duplicate-read-guard'
 import { investigation_refusal } from '#scripts/delegation/investigation-guard'
-import { hook_decision, type GuardOutcome } from '#scripts/josh/hook-decision'
+import type { GuardOutcome } from '#scripts/josh/hook-decision'
 import { delivered_rules } from '#scripts/rules/delivered-rules'
+import { run_parent_cut_hook } from '#scripts/run/run-parent-cut-hook'
 import { run_watcher_hook } from '#scripts/run/run-watcher-hook'
 import { batch_outcome } from './batch-guard'
+import { step_zero_notice } from './step-zero-notice'
 
 // One PreToolUse process for the three guards that used to be three (joshuafolkken/kit#1930). A Bash
 // call used to spawn `batch:guard`, `investigation:guard` and `rule:guard` separately — three pnpm
@@ -51,10 +50,20 @@ function with_duplicate_notice(combined: GuardOutcome, notice: string | undefine
 	return { reason: undefined, notice, fault: undefined }
 }
 
+// The Step 0 reminder is the last word (joshuafolkken/kit#2994): 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 {
+	if (!is_clear(outcome)) return outcome
+
+	const notice = step_zero_notice.notice(raw_payload)
+
+	return notice === undefined ? outcome : { reason: undefined, notice, fault: undefined }
+}
+
 // All guards run unconditionally, exactly as the separate PreToolUse entries did: each records its own
 // once-per-run stamp, so short-circuiting on the first refusal would change which guard is allowed to
 // fire on a later call.
-function pretool_outcome(raw_payload: string): GuardOutcome {
+function guard_outcome(raw_payload: string): GuardOutcome {
 	const batch = batch_outcome(raw_payload)
 	const investigation = investigation_refusal(raw_payload)
 	const duplicate = duplicate_read_outcome(raw_payload)
@@ -65,32 +74,40 @@ function pretool_outcome(raw_payload: string): GuardOutcome {
 	return with_duplicate_notice(combined, duplicate.notice)
 }
 
+// The synchronous verdict the Codex adapter asks for, with the Step 0 reminder as its last layer.
+function pretool_outcome(raw_payload: string): GuardOutcome {
+	return with_step_zero_notice(guard_outcome(raw_payload), raw_payload)
+}
+
 // The watcher guard is the one composed rule that cannot answer synchronously — it reads the lane
 // registry and the watcher's life record off disk (joshuafolkken/kit#2353). So it is asked after the
 // synchronous guards and only where they stayed clear: a refusal from any of them wins first, exactly
 // as `combine_outcomes` orders them, and the watcher's refusal fills a clear verdict rather than
 // overriding one. It fires once per run itself (`run-watcher-hook.ts`), so a stale watcher refuses the
 // first call but not the `pnpm josh run:progress --wait` that fixes it.
+//
+// **The parent hand-off guard is the second asynchronous rule, asked after the watcher's**
+// (joshuafolkken/kit#2947). It reads the carry record to tell the `backlogrun` parent apart, so it sits
+// beside the watcher rather than among the synchronous rows; a stale watcher is the cheaper fix and is
+// surfaced first.
+async function async_reason(raw_payload: string): Promise<string | undefined> {
+	const watcher = await run_watcher_hook.watcher_hook_reason(raw_payload)
+
+	return watcher ?? (await run_parent_cut_hook.parent_cut_reason(raw_payload))
+}
+
 async function pretool_outcome_async(raw_payload: string): Promise<GuardOutcome> {
-	const base = pretool_outcome(raw_payload)
+	const base = guard_outcome(raw_payload)
 
 	if (!is_clear(base)) return base
 
-	const reason = await run_watcher_hook.watcher_hook_reason(raw_payload)
-
-	return reason === undefined ? base : { reason, notice: undefined, fault: undefined }
-}
-
-const pretool_guard = { combine_outcomes, pretool_outcome, pretool_outcome_async }
+	const reason = await async_reason(raw_payload)
 
-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)
+	if (reason !== undefined) return { reason, notice: undefined, fault: undefined }
 
-		hook_decision.load_environment_file()
-		hook_decision.emit_outcome(await pretool_outcome_async(raw_payload))
-	}
+	return with_step_zero_notice(base, raw_payload)
 }
 
+const pretool_guard = { combine_outcomes, pretool_outcome }
+
 export { pretool_guard, pretool_outcome, pretool_outcome_async }

package/scripts/hooks/reserved-run.ts

@@ -85,6 +85,6 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
 	process.exitCode = await run_reserved(process.argv.slice(FIRST_ARGUMENT_INDEX))
 }
 
-const reserved_run = { parse_arguments, run_command, run_reserved }
+const reserved_run = { parse_arguments, run_reserved }
 
 export { reserved_run }

package/scripts/hooks/step-zero-notice.ts

@@ -0,0 +1,76 @@
+import path from 'node:path'
+import { hook_decision } from '#scripts/josh/hook-decision'
+import { json_value } from '#scripts/lib/json-value'
+import { test_declared_logic } from '#scripts/test/test-declared-logic'
+
+// The Code Change Rules Step 0 reminder, delivered at the moment implementation code is about to be
+// written rather than on every prompt (joshuafolkken/kit#2994). As a `UserPromptSubmit` echo it was
+// injected into every turn — a question that writes nothing included — and re-read as accumulated
+// context on each turn after it. The trigger the rule names is "before writing any implementation
+// code", so the hook that delivers it is the one that sees that write: the first `Edit` / `Write` of a
+// runtime file in the session.
+//
+// **A runtime file only.** What counts is `test_declared_logic.is_exempt`, the same classification
+// `pnpm josh test:declared` answers at the commit, so a doc or prompt edit neither shows the notice nor
+// spends it. A path outside the working tree (a memory file, a scratchpad) is not this project's code.
+//
+// **Once per session**, on a stamp keyed by the transcript like every other guard record here. A stamp
+// that cannot be written stays silent rather than repeating the notice on every edit.
+const STAMP_PREFIX = 'josh-step-zero-notice-'
+const EDIT_TOOLS: ReadonlySet<string> = new Set(['Edit', 'Write'])
+const PARENT_PREFIX = '..'
+
+const NOTICE =
+	'Before writing any implementation code: present the two-layer work summary (Now / Change / Check, then every change with its test) once per Issue. Full rule: Code Change Rules Step 0 in CLAUDE.md.'
+
+const STAMP = hook_decision.create_refusal_stamp(STAMP_PREFIX)
+
+// A Codex `apply_patch` arrives translated with its first file as `file_path` and every file in
+// `file_paths`, so a patch that leads with a doc and also writes code is still a runtime write.
+function edited_paths(tool_input: unknown): Array<string> {
+	if (!json_value.is_record(tool_input)) return []
+
+	const { file_path, file_paths } = tool_input
+	const listed: ReadonlyArray<unknown> = Array.isArray(file_paths) ? file_paths : []
+
+	return [file_path, ...listed].filter(
+		(entry): entry is string => typeof entry === 'string' && entry.length > 0,
+	)
+}
+
+function is_runtime_file(file_path: string, root: string): boolean {
+	const relative = path.relative(root, path.resolve(root, file_path))
+
+	if (relative.startsWith(PARENT_PREFIX) || path.isAbsolute(relative)) return false
+
+	return !test_declared_logic.is_exempt(relative.split(path.sep).join('/'))
+}
+
+function is_candidate(raw_payload: string, root: string): string | undefined {
+	const payload = hook_decision.parse_hook_payload(raw_payload)
+
+	if (payload === undefined || !EDIT_TOOLS.has(payload.tool_name)) return undefined
+
+	const has_runtime_file = edited_paths(payload.tool_input).some((file_path) =>
+		is_runtime_file(file_path, root),
+	)
+
+	return has_runtime_file ? payload.transcript_path : undefined
+}
+
+function notice(raw_payload: string, root: string = process.cwd()): string | undefined {
+	const transcript = is_candidate(raw_payload, root)
+
+	if (transcript === undefined) return undefined
+
+	const target = STAMP.path(transcript)
+
+	if (STAMP.last_ms(target) !== hook_decision.NEVER_MS) return undefined
+	if (!STAMP.record(target, Date.now())) return undefined
+
+	return NOTICE
+}
+
+const step_zero_notice = { NOTICE, notice, stamp_path: STAMP.path }
+
+export { step_zero_notice }

package/scripts/hooks/stop-guard.ts

@@ -7,12 +7,15 @@ import { repo_party } from '#scripts/discovery/repo-party'
 import { hook_decision } from '#scripts/josh/hook-decision'
 import { session_language } from '#scripts/josh/session-language'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
+import { lane_handoff } from '#scripts/lane/lane-handoff'
 import { filing_cap } from '#scripts/rules/filing-cap'
 import { lane_background } from '#scripts/rules/lane-background'
 import { lane_park } from '#scripts/rules/lane-park'
 import { last_prompt } from '#scripts/rules/last-prompt'
 import { stop_rules, type StopContext, type StopOutcome } from '#scripts/rules/stop-rules'
+import { run_carry } from '#scripts/run/run-carry'
 import { run_cut } from '#scripts/run/run-cut'
+import { run_halfrun_resume } from '#scripts/run/run-halfrun-resume'
 import { run_headless } from '#scripts/run/run-headless'
 import { run_hold } from '#scripts/run/run-hold'
 import { run_stranded_detect } from '#scripts/run/run-stranded-detect'
@@ -29,16 +32,17 @@ import { time_hook_transcript } from '#scripts/time-runtime/time-hook-transcript
 // resolving (send the notify, release the hold) and `stop_hook_active` is the backstop, so failing
 // open here costs at most a missed nudge, never a stuck run.
 
-// The hold record for this working tree is still in place. `unreadable` reads as absent: the safe
-// direction for a stop guard is not to block, and an unreadable record is not proof a run is holding.
-async function is_hold_present(): Promise<boolean> {
+// The hold record for this working tree is still in place, and whether it is a `prrun` stop's
+// (joshuafolkken/kit#3023). `unreadable` reads as absent: the safe direction for a stop guard is not to
+// block, and an unreadable record is not proof a run is holding.
+async function hold_facts(): Promise<Pick<StopContext, 'hold_present' | 'prrun_stopped'>> {
 	const directory = await run_hold.worktree_directory()
+	const hold =
+		directory === undefined
+			? undefined
+			: run_halfrun_resume.hold_of(run_hold.read_hold(run_hold.hold_path(directory)))
 
-	if (directory === undefined) return false
-
-	const read = run_hold.read_hold(run_hold.hold_path(directory))
-
-	return read.kind === 'held' || read.kind === 'stale'
+	return { hold_present: hold !== undefined, prrun_stopped: hold?.prrun_stop_head !== undefined }
 }
 
 // A `confirmation` notify sits on this run's transcript tail. The tail is derived exactly as the
@@ -67,7 +71,7 @@ async function build_context(
 	const tail = transcript_tail(transcript_path)
 
 	return {
-		hold_present: await is_hold_present(),
+		...(await hold_facts()),
 		tree_clean: !(await run_hold.is_tree_dirty()),
 		notified: lane_park.mentions_confirmation_notify(tail),
 		message: payload_tail.message,
@@ -81,6 +85,7 @@ async function build_context(
 		lane_child: lane_child_marker.is_child_of(process.cwd()),
 		background_pending: lane_background.pending_background_ids(tail).length > 0,
 		agent_pending: lane_background.pending_agent_ids(tail).length > 0,
+		handed_off: lane_handoff.is_handed_off(process.cwd()),
 		session_lang: session_lang(),
 	}
 }
@@ -106,22 +111,43 @@ async function outcome_of(raw_payload: string): Promise<StopOutcome> {
 	}
 }
 
+// A live carry record is in place — `carried` alone reads as a run. Both report checks below are about
+// a carried run: the strand judge reads this very record and returns on anything but `carried`, and a
+// stall needs a backlog driver, which begins one before its plan. A spent (`expired`) or `unreadable`
+// record a crashed run left behind is no run either, so it does not re-arm the stall's backlog probe
+// on every stop (joshuafolkken/kit#2995).
+// A failed git read — outside a repository, `git rev-parse` exits non-zero — reads as no run, since this
+// gate sits ahead of the checks' own swallowing and must not throw into the stop decision either.
+async function has_run_record(): Promise<boolean> {
+	try {
+		const directory = await run_carry.repository_directory()
+
+		if (directory === undefined) return false
+
+		return run_carry.read_carry(run_carry.carry_path(directory)).kind === 'carried'
+	} catch {
+		return false
+	}
+}
+
+// The stall check rides the Stop hook because the stop *is* the loop boundary: a run alive but not
+// advancing ends turns without dispatching (joshuafolkken/kit#2359). The strand check rides the same
+// boundary and is the step before the stall (joshuafolkken/kit#2375): it fires when the driver is gone
+// — the budget handed off, the owner dead, no supervisor watching. Both only report and swallow their
+// own failures, so neither can change the stop decision. An ordinary stop with no run record skips
+// both, so it pays one directory read rather than their reads and a stale stream's backlog probe.
+async function run_report_checks(): Promise<void> {
+	if (!(await has_run_record())) return
+
+	await backlog_stalled_detect.run_stall_check(backlog_ready.DEFAULT_PORTS)
+	await run_stranded_detect.run_stranded_check()
+}
+
 // Nothing reaches stdout on an ordinary stop, so what the harness parses stays empty unless the stop
 // is being held — all three rules block, so a bare `#N` is reported the same way (joshuafolkken/kit#2247).
 async function write_stop_decision(raw_payload: string): Promise<void> {
 	hook_decision.load_environment_file()
-
-	// The stall check rides the Stop hook because the stop *is* the loop boundary: a run alive but not
-	// advancing ends turns without dispatching (joshuafolkken/kit#2359). It only reports — leaves a
-	// marker, sends a notification — and swallows its own failures, so it can never change the decision
-	// below or hold the stop.
-	await backlog_stalled_detect.run_stall_check(backlog_ready.DEFAULT_PORTS)
-
-	// The strand check rides the same boundary for the same reason, and is the step before the stall
-	// (joshuafolkken/kit#2375): the stall detector needs a live driver that could dispatch, and this one
-	// fires when that driver is gone — the budget handed off, the owner dead, no supervisor watching. It
-	// too only reports and swallows its own failures, so it never touches the stop decision below.
-	await run_stranded_detect.run_stranded_check()
+	await run_report_checks()
 
 	const { reason } = await outcome_of(raw_payload)
 

package/scripts/init/claude-plugin-config.ts

@@ -13,9 +13,10 @@ const PLUGIN_ID = 'kit@kit'
 const MARKETPLACE_PATH = './node_modules/@joshuafolkken/kit'
 const CLAUDE_SETTINGS_DESTINATION = path.join('.claude', 'settings.json')
 
-// `enabledPlugins` declares the plugin; `extraKnownMarketplaces` says where to find it. The CLI does
-// not auto-install from these alone — a consumer runs `claude plugin install kit@kit` once — so the
-// declaration is what makes that one command resolve without further arguments.
+// `enabledPlugins` declares the plugin; `extraKnownMarketplaces` says where to find it. Nothing needs
+// installing: in a trusted workspace Claude Code registers the marketplace from this declaration and
+// loads the skills — an interactive session from its first session, a headless one (`claude -p`) from
+// its second (joshuafolkken/kit#2990).
 const PLUGIN_SETTINGS: Record<string, unknown> = {
 	extraKnownMarketplaces: {
 		[MARKETPLACE_NAME]: { source: { source: 'directory', path: MARKETPLACE_PATH } },
@@ -39,11 +40,9 @@ function apply_plugin_config_for_destination(destination_path: string, content:
 }
 
 const claude_plugin_config = {
-	MARKETPLACE_NAME,
 	PLUGIN_ID,
 	MARKETPLACE_PATH,
 	CLAUDE_SETTINGS_DESTINATION,
-	PLUGIN_SETTINGS,
 	inject_plugin_config,
 	apply_plugin_config_for_destination,
 }

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

@@ -1,4 +1,3 @@
-import { GIT_LOCATION_VARIABLES } from '#scripts/git/git-location-environment'
 import { claude_plugin_config } from './claude-plugin-config'
 import { hook_launch } from './hook-launch'
 
@@ -27,8 +26,11 @@ const MISSING_INSTALL_NOTICE = 'kit hooks inactive: run pnpm install, then rerea
 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'
-const GIT_UNSET_OPTIONS = GIT_LOCATION_VARIABLES.map((name) => `-u ${name}`).join(' ')
-const PROJECT_ROOT_PREFIX = String.raw`if project_root=\"$(env ${GIT_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\" && `
+// 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
@@ -49,6 +51,8 @@ function rebase_bundle_directory(value: string): string {
 // holds no `pnpm josh `), so 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)
 		.split(PNPM_JOSH_PREFIX)
 		.join(BUNDLE_INVOCATION)
 		.split(CODEX_ADAPTER_SOURCE)
@@ -60,12 +64,18 @@ function rewrite_command_value(value: string): string {
 	return `${MISSING_INSTALL_GUARD}${rewritten}`
 }
 
+// kit's own commands already start from the root (`hook-launch.ts`), and so does an already-rewritten
+// value. The prefix is taken off before the rewrite and put back after it, so the install guard sits
+// behind the `cd` it depends on and a second pass never doubles the prefix.
+function without_root_prefix(value: string): string {
+	return value.startsWith(PROJECT_ROOT_PREFIX) ? value.slice(PROJECT_ROOT_PREFIX.length) : value
+}
+
 function rewrite_hook_commands(content: string, is_codex = false): string {
 	return content.replaceAll(COMMAND_FIELD, (_match, open: string, value: string, close: string) => {
-		const rewritten = rewrite_command_value(value)
+		const rewritten = rewrite_command_value(without_root_prefix(value))
 		const should_select_root = is_codex || rewritten.includes(claude_plugin_config.MARKETPLACE_PATH)
-		const prefix =
-			should_select_root && !rewritten.startsWith(PROJECT_ROOT_PREFIX) ? PROJECT_ROOT_PREFIX : ''
+		const prefix = should_select_root ? PROJECT_ROOT_PREFIX : ''
 
 		return `${open}${prefix}${rewritten}${close}`
 	})
@@ -89,8 +99,6 @@ function apply_hook_command_rewrite_for_destination(
 
 const hook_command_rewrite = {
 	apply_hook_command_rewrite_for_destination,
-	BUNDLE_INVOCATION,
-	PNPM_JOSH_PREFIX,
 	rewrite_hook_commands,
 }
 

package/scripts/init/hook-launch.ts

@@ -1,31 +1,57 @@
+import { GIT_LOCATION_VARIABLES } from '#scripts/git/git-location-environment'
+
 // The shell command a Claude Code hook is launched with, so it starts without a `pnpm` wrapper — and,
 // for a consumer, without the `dist/josh.js` dispatcher re-spawning `tsx` for the hook's `.ts`
 // (joshuafolkken/kit#2023). Each hook is pre-built to its own `dist/hooks/<name>.js`
 // (`scripts/build/build-hooks.ts`) and launched directly with `node`.
 //
-// **The fallback is a real branch, not a courtesy.** A fresh clone has no `dist/hooks/` until
-// `pnpm build` runs, so the command prefers the bundle and drops to `pnpm josh <command>` (the live
-// `tsx` source) when the bundle is absent, rather than passing silently. **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. `[ -f ]` decides on the file alone and
-// leaves the chosen branch's exit code untouched.
-
-// Relative to the working directory a hook runs in — kit's own root, where the built `dist/hooks/`
-// sits. The consumer rewrite (`hook-command-rewrite.ts`) rebases this onto the installed package.
+// **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.
+//
+// **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.
+
 const HOOK_DIST_DIR = 'dist/hooks'
+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'
 
-// Prefer `primary_path` (run as `node <path>`) when it exists, else run `fallback_command` verbatim.
-// Kept generic so a test can exercise the branch selection with stub commands rather than real hooks.
-function launch_command(primary_path: string, fallback_command: string): string {
-	return `if [ -f ${primary_path} ]; then node ${primary_path}; else ${fallback_command}; fi`
+// 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`
+}
+
+// `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 launch_command(`${HOOK_DIST_DIR}/${bundle}`, `pnpm josh ${command}`)
+	return bundle_launch_command(bundle, `pnpm josh ${command}`)
 }
 
-const hook_launch = { HOOK_DIST_DIR, hook_launch_command, launch_command }
+const hook_launch = {
+	BUNDLE_READY_GATE,
+	bundle_launch_command,
+	HOOK_DIST_DIR,
+	hook_launch_command,
+	launch_command,
+	PROJECT_ROOT_PREFIX,
+}
 
 export { hook_launch }

package/scripts/init/init-basic.ts

@@ -1,4 +1,5 @@
 import { json_format } from '#scripts/config-merge/json-format'
+import { json_value } from '#scripts/lib/json-value'
 import { z } from 'zod'
 import { init_logic } from './init-logic'
 import type { ProjectShape } from './project-profile'
@@ -6,10 +7,6 @@ import type { ProjectShape } from './project-profile'
 const KIT_PACKAGE_NAME = '@joshuafolkken/kit'
 const record_schema = z.record(z.string(), z.unknown())
 
-function is_record(value: unknown): value is Record<string, unknown> {
-	return typeof value === 'object' && value !== null && !Array.isArray(value)
-}
-
 interface BasicVersions {
 	kit: string
 	prettier: string
@@ -23,7 +20,7 @@ function with_recorded_profile(content: string, profile: ProjectShape['profile']
 	const parsed: unknown = JSON.parse(content)
 	const manifest = record_schema.parse(parsed)
 	const existing = manifest['josh']
-	const josh = is_record(existing) ? existing : {}
+	const josh = json_value.is_record(existing) ? existing : {}
 
 	manifest['josh'] = { ...josh, profile }
 

package/scripts/init/init-logic.ts

@@ -92,6 +92,10 @@ const AI_COPY_FILES: ReadonlyArray<string> = [
 	'.github/workflows/production.yml',
 	'.github/workflows/sonar-qube.yml',
 	'.github/workflows/pr-classification.yml',
+	// Called by `pr-classification.yml` as `uses: ./.github/actions/setup-pnpm`; without it the
+	// consumer's job cannot resolve the action and the Release classification check fails
+	// (joshuafolkken/kit#3013).
+	'.github/actions/setup-pnpm/action.yml',
 	'.github/pull_request_template.md',
 	'.github/release.yml',
 	'.github/dependabot.yml',
@@ -118,6 +122,9 @@ const AI_COPY_FILE_MAPPINGS: ReadonlyArray<FileCopyMapping> = [
 		src: 'templates/workflows/dependabot-auto-merge.yml',
 		dest: '.github/workflows/dependabot-auto-merge.yml',
 	},
+	// A template rather than a copy of kit's own file: kit releases from its publish.yml, so the file
+	// must not run in kit as well (joshuafolkken/kit#3007).
+	{ src: 'templates/workflows/github-release.yml', dest: '.github/workflows/github-release.yml' },
 ]
 
 // Empty since joshuafolkken/kit#1879: the five skill directories kit used to copy whole

package/scripts/init/init.ts

@@ -22,7 +22,6 @@ import { init_install } from './init-install'
 import { init_logic } from './init-logic'
 import { PACKAGE_DIR, PROJECT_ROOT } from './init-paths'
 import { kit_setup_state } from './kit-setup-state'
-import { plugin_install_hint_module } from './plugin-install-hint'
 import { project_profile, type ProjectProfile, type ProjectShape } from './project-profile'
 
 const PACKAGE_JSON = 'package.json'
@@ -295,8 +294,6 @@ function run_ai_file_actions(shape: ProjectShape): void {
 	const name_with_owner = init_ai_copy.run_ai_copies(shape)
 
 	if (shape.has_github) report_repository_settings(name_with_owner)
-
-	if (shape.profile === 'full') plugin_install_hint_module.report_plugin_install_hint()
 }
 
 function initialize_project(shape: ProjectShape): void {

package/scripts/init/project-profile.ts

@@ -1,6 +1,7 @@
 import { existsSync, readdirSync, readFileSync, type Dirent } from 'node:fs'
 import path from 'node:path'
 import { repo_origin } from '#scripts/discovery/repo-origin'
+import { json_value } from '#scripts/lib/json-value'
 import { KIT_PACKAGE_NAME } from '#scripts/version/kit-descriptor'
 import { execaSync } from 'execa'
 
@@ -73,32 +74,26 @@ function read_manifest(root: string): Record<string, unknown> | undefined {
 	if (!existsSync(filename)) return undefined
 	const parsed: unknown = JSON.parse(readFileSync(filename, 'utf8'))
 
-	if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
-		throw new Error('package.json must contain an object')
-	}
-
-	return parsed as Record<string, unknown>
-}
+	if (!json_value.is_record(parsed)) throw new Error('package.json must contain an object')
 
-function is_record(value: unknown): value is Record<string, unknown> {
-	return typeof value === 'object' && value !== null && !Array.isArray(value)
+	return parsed
 }
 
 function recorded_profile(manifest: Record<string, unknown>): ProjectProfile | undefined {
 	const { josh } = manifest
 
-	return is_record(josh) ? parse_profile(josh['profile']) : undefined
+	return json_value.is_record(josh) ? parse_profile(josh['profile']) : undefined
 }
 
 function has_build_script(value: unknown): boolean {
-	return is_record(value) && ('build' in value || 'dev' in value)
+	return json_value.is_record(value) && ('build' in value || 'dev' in value)
 }
 
 // kit itself is not evidence of a Node toolchain: `pnpm add -D @joshuafolkken/kit` before
 // `josh init` is the documented order, and it must still leave an `index.html` site on the basic
 // profile (joshuafolkken/kit#2693).
 function has_project_dependencies(value: unknown): boolean {
-	if (!is_record(value)) return false
+	if (!json_value.is_record(value)) return false
 
 	return Object.keys(value).some((name) => name !== KIT_PACKAGE_NAME)
 }

package/scripts/init/start-exec.ts

@@ -1,4 +1,4 @@
-import { git_gh_exec } from '#scripts/git/git-gh-exec'
+import { git_gh_exec } from '#scripts/gh/git-gh-exec'
 import { execaSync } from 'execa'
 
 // The three spawn shapes every `josh start` step uses, shared by `start-steps.ts`, the setup pull
@@ -23,6 +23,12 @@ function run(command: string, args: ReadonlyArray<string>, root: string): void {
 	execaSync(command, args, { ...git_gh_exec.direct_environment(), cwd: root, stdio: 'inherit' })
 }
 
-const start_exec = { succeeds, read_output, run }
+// A caller's own initialize command stands in for the in-process `josh init`, so it keeps the
+// environment that setup would have had — its install goes through a scanner's proxy as usual.
+function run_local(command: string, args: ReadonlyArray<string>, root: string): void {
+	execaSync(command, args, { cwd: root, stdio: 'inherit' })
+}
+
+const start_exec = { succeeds, read_output, run, run_local }
 
 export { start_exec }