@joshuafolkken/kit 1.2114.0 → 1.3000.0

package/scripts/hooks/stop-actions.ts

@@ -55,13 +55,20 @@ function summary_of(message: string): string {
 	return cut === '' ? trimmed.slice(0, SUMMARY_CHARS) : cut
 }
 
-// The held Issue's URL, or `undefined` for a `new` entry or a repository that cannot be read.
+// The held Issue's URL, or `undefined` for a `new` entry or a repository that cannot be read. The URL
+// is optional: a lookup that throws (an exhausted rate limit) is warned and the confirmation goes bare.
 async function issue_url_of(issue: string): Promise<string | undefined> {
 	if (issue === run_hold.UNNUMBERED_ISSUE) return undefined
 
-	const slug = await git_gh_repo.repo_get_name_with_owner()
+	try {
+		const slug = await git_gh_repo.repo_get_name_with_owner()
+
+		return slug === undefined ? undefined : issue_cite.issue_url(slug, issue)
+	} catch (error) {
+		console.warn(`stop:guard could not resolve the Issue URL, sending without it: ${String(error)}`)
 
-	return slug === undefined ? undefined : issue_cite.issue_url(slug, issue)
+		return undefined
+	}
 }
 
 // The body is the reply's opening copied into a Telegram, so its bare `#N` are linked (`issue-citation.md`).

package/scripts/hooks/stop-guard.ts

@@ -4,6 +4,7 @@ import { agent_headless } from '#scripts/agent/agent-headless'
 import { backlog_ready } from '#scripts/backlog/backlog-ready'
 import { backlog_stalled_detect } from '#scripts/backlog/backlog-stalled-detect'
 import { repo_party } from '#scripts/discovery/repo-party'
+import { hook_ledger } from '#scripts/hooks/hook-ledger'
 import { stop_actions } from '#scripts/hooks/stop-actions'
 import { hook_decision } from '#scripts/josh/hook-decision'
 import { session_language } from '#scripts/josh/session-language'
@@ -26,8 +27,8 @@ import { run_hold_session } from '#scripts/run/hold/run-hold-session'
 import { run_halfrun_resume } from '#scripts/run/run-halfrun-resume'
 import { run_headless } from '#scripts/run/run-headless'
 import { run_stranded_detect } from '#scripts/run/run-stranded-detect'
-import { time_density_hook } from '#scripts/time-runtime/time-density-hook'
 import { time_hook_transcript } from '#scripts/time-runtime/time-hook-transcript'
+import { transcript_tail } from '#scripts/time-runtime/transcript-tail'
 
 // The `Stop` hook entry: one process that delivers the stop-time rules, running the fixed ones itself
 // (`stop-actions.ts`).
@@ -40,6 +41,9 @@ import { time_hook_transcript } from '#scripts/time-runtime/time-hook-transcript
 // operations itself (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 name a refusal is recorded under in the hook ledger (`hook-ledger.ts`).
+const HOOK_NAME = 'stop-guard'
+
 // The hold record for this working tree. `unreadable` reads as absent: the safe direction for a stop
 // guard is not to act, and an unreadable record is not proof a run is holding.
 async function held_record(): Promise<RunHold | undefined> {
@@ -76,10 +80,10 @@ async function hold_facts(
 
 // A `confirmation` notify sits on this run's transcript tail. The tail is derived exactly as the
 // PreToolUse guards derive it, and the judgement is `lane-park`'s, reused rather than re-spelled.
-function transcript_tail(transcript_path: string): string {
+function session_tail(transcript_path: string): string {
 	const transcript = time_hook_transcript.transcript_of(transcript_path, undefined)
 
-	return time_density_hook.read_tail(transcript)
+	return transcript_tail.read_tail(transcript)
 }
 
 // An Issue was filed on this turn — the tail from the last prompt on. The count is `turn_filings`', so
@@ -109,21 +113,22 @@ function session_lang(): string {
 // Which session this is — a headless parent, a lane child, a kit-launched agent, the `backlogrun`
 // parent — the facts that say whether a person is there to answer.
 async function session_role_facts(): Promise<
-	Pick<StopContext, 'backlog_parent' | 'headless_agent' | 'headless_waiting' | 'lane_child'>
+	Pick<StopContext, 'backlog_parent' | 'headless_agent' | 'lane_child'>
 > {
 	return {
-		headless_waiting: await run_headless.must_keep_waiting(),
 		lane_child: lane_child_marker.is_child_of(process.cwd()),
 		headless_agent: agent_headless.is_headless(),
 		backlog_parent: await run_headless.is_backlog_parent(),
 	}
 }
 
+type PassContext = Omit<StopContext, 'headless_waiting'>
+
 async function build_context(
 	transcript_path: string,
 	payload_tail: { stop_hook_active: boolean; message: string },
-): Promise<StopContext> {
-	const tail = transcript_tail(transcript_path)
+): Promise<PassContext> {
+	const tail = session_tail(transcript_path)
 
 	return {
 		...(await hold_facts(tail)),
@@ -145,6 +150,20 @@ async function build_context(
 	}
 }
 
+// **A headless parent's cut is written only once no other rule refuses the stop**
+// (joshuafolkken/kit#5739). Its turn-end is its process's end, so the stop is where
+// `run_headless.hand_back_at_turn_end` hands the loop back; a cut written before another refusal would
+// hand off a record the continued session still counts on. The headless wait is asked only after the
+// write, where it means the write lost.
+async function hand_back_outcome(context: PassContext): Promise<StopOutcome> {
+	const released = stop_rules.stop_outcome({ ...context, headless_waiting: false })
+	if (released.reason !== undefined) return released
+
+	const is_waiting = await run_headless.hand_back_at_turn_end()
+
+	return is_waiting ? stop_rules.stop_outcome({ ...context, headless_waiting: true }) : released
+}
+
 async function stop_outcome_for_payload(raw_payload: string): Promise<StopOutcome> {
 	const payload = stop_rules.parse_stop_payload(raw_payload)
 
@@ -155,7 +174,7 @@ async function stop_outcome_for_payload(raw_payload: string): Promise<StopOutcom
 		message: payload.last_assistant_message ?? '',
 	})
 
-	return stop_rules.stop_outcome(context)
+	return await hand_back_outcome(context)
 }
 
 async function outcome_of(raw_payload: string): Promise<StopOutcome> {
@@ -225,6 +244,8 @@ async function write_stop_decision(raw_payload: string): Promise<void> {
 	if (envelope === undefined) return
 
 	process.stdout.write(`${envelope}\n`)
+	// Read off the written envelope, so a stop held by a failed action is counted beside a bare reason.
+	await hook_ledger.record_reason(HOOK_NAME, hook_ledger.blocked_reason(envelope), raw_payload)
 }
 
 const stop_guard = { outcome_of, stop_outcome_for_payload }

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

@@ -2,7 +2,7 @@ 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,
+// false` keeps the Artifact tool's definition out of every call of a kit run,
 // 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']

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

@@ -14,26 +14,35 @@ import { hook_launch } from './hook-launch'
 // transformed in place.
 
 const PNPM_JOSH_PREFIX = 'pnpm josh '
-// 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 `
-// 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 { MARKETPLACE_PATH } = claude_plugin_config
+// The installed package below the project root, as a rooted path names it.
+const PACKAGE_PATH = MARKETPLACE_PATH.replace(/^\.\//u, '')
+const INSTALLED_LAUNCHER = `${PACKAGE_PATH}/${hook_launch.RUN_HOOK_SCRIPT}`
+const INSTALLED_DISPATCHER = `${PACKAGE_PATH}/dist/josh.js`
+const INSTALLED_MANIFEST = `${PACKAGE_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_HOOKS_DESTINATION = '.codex/hooks.json'
-// Every shape a hook command kit wrote can carry: the launcher as kit's own file names it, the
-// launcher rebased onto the installed package, and the installed dispatcher the releases from
-// 2026-09-13 (joshuafolkken/kit#1930) to the launcher rebased `pnpm josh` onto. The settings merge
-// tells kit's hooks from a project's own by these and the list below, so the shapes stay beside the
-// rewrite that produces them.
-const KIT_COMMAND_MARKERS: ReadonlyArray<string> = [
-	RUN_HOOK_INVOCATION,
-	CONSUMER_RUN_HOOK_INVOCATION,
-	BUNDLE_INVOCATION,
+
+// Each shape a hook command took while it moved to the project root first and named every path
+// relative to it, before joshuafolkken/kit#6033 named the launcher by its absolute path. The settings
+// merge still tells a consumer's not-yet-synced kit hooks by these. History, never edited; removable
+// from kit 2.0.0.
+const RELATIVE_RUN_HOOK_INVOCATION = `sh ${hook_launch.RUN_HOOK_SCRIPT} `
+const RELATIVE_CONSUMER_RUN_HOOK_INVOCATION = `sh ${MARKETPLACE_PATH}/${hook_launch.RUN_HOOK_SCRIPT} `
+// The installed dispatcher the releases from 2026-09-13 (joshuafolkken/kit#1930) rebased `pnpm josh`
+// onto.
+const RELATIVE_BUNDLE_INVOCATION = `node ${MARKETPLACE_PATH}/dist/josh.js `
+const RELATIVE_INSTALL_GUARD = `if [ ! -f ${MARKETPLACE_PATH}/package.json ]; then echo '${MISSING_INSTALL_NOTICE}' >&2; exit 0; fi; `
+const LOCATION_VARIABLES =
+	'GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_DIR GIT_INDEX_FILE GIT_NAMESPACE GIT_OBJECT_DIRECTORY GIT_WORK_TREE'
+const ROOT_LOOKUP = 'git rev-parse --show-toplevel'
+const LOCATION_FREE_ROOT = `$( (unset ${LOCATION_VARIABLES}; ${ROOT_LOOKUP} 2>/dev/null) || ${ROOT_LOOKUP})`
+// The root prefixes, newest first: until joshuafolkken/kit#6033, until #4617 (no launch directory)
+// and until #4187 (the git location variables cleared here rather than in the launcher).
+const ROOT_PREFIXES: ReadonlyArray<string> = [
+	`export JOSH_HOOK_CWD="$PWD" && project_root="\${CLAUDE_PROJECT_DIR:-${LOCATION_FREE_ROOT}}" && cd "$project_root" && `,
+	`project_root="\${CLAUDE_PROJECT_DIR:-${LOCATION_FREE_ROOT}}" && cd "$project_root" && `,
+	`if project_root="$(unset ${LOCATION_VARIABLES}; ${ROOT_LOOKUP} 2>/dev/null)"; then unset ${LOCATION_VARIABLES}; else project_root="$(${ROOT_LOOKUP})"; fi && cd "$project_root" && `,
 ]
 // Before joshuafolkken/kit#1930 nothing was rebased: a consumer received these six as the whole hook
 // command. A plain `pnpm josh <command>` is also how a project writes a hook of its own, so only the
@@ -49,65 +58,81 @@ const PLAIN_KIT_COMMANDS: ReadonlySet<string> = new Set(
 		'session:lang',
 	].map((command) => `${PNPM_JOSH_PREFIX}${command}`),
 )
-// The root prefix kit wrote until joshuafolkken/kit#4187 moved the git location variables into the
-// launcher. A consumer's file still carries it until its next sync, which replaces it with the current
-// one. History, never edited; removable from kit 2.0.0.
-const LOCATION_VARIABLES =
-	'GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_DIR GIT_INDEX_FILE GIT_NAMESPACE GIT_OBJECT_DIRECTORY GIT_WORK_TREE'
-const ROOT_LOOKUP = 'git rev-parse --show-toplevel'
-const LEGACY_ROOT_PREFIX = `if project_root="$(unset ${LOCATION_VARIABLES}; ${ROOT_LOOKUP} 2>/dev/null)"; then unset ${LOCATION_VARIABLES}; else project_root="$(${ROOT_LOOKUP})"; fi && cd "$project_root" && `
-// The root prefix kit wrote until joshuafolkken/kit#4617 exported the launch directory for a worktree.
-// History, never edited; removable from kit 2.0.0.
-const PRE_WORKTREE_ROOT_PREFIX = `project_root="\${CLAUDE_PROJECT_DIR:-$( (unset ${LOCATION_VARIABLES}; ${ROOT_LOOKUP} 2>/dev/null) || ${ROOT_LOOKUP})}" && cd "$project_root" && `
-// The values below are matched inside raw JSON text, so each root prefix is taken in its escaped form.
-const ROOT_PREFIXES: ReadonlyArray<string> = [
-	hook_launch.PROJECT_ROOT_PREFIX,
-	PRE_WORKTREE_ROOT_PREFIX,
-	LEGACY_ROOT_PREFIX,
-].map((prefix) => JSON.stringify(prefix).slice(1, -1))
-const [PROJECT_ROOT_PREFIX = ''] = ROOT_PREFIXES
+// Every shape a hook command kit wrote can carry: the launcher under any root, kit's or the installed
+// package's, the installed dispatcher under any root, and the relative shapes above. The settings merge
+// tells kit's hooks from a project's own by these and the list above, so the shapes stay beside the
+// rewrite that produces them.
+const KIT_COMMAND_MARKERS: ReadonlyArray<string> = [
+	`/${hook_launch.RUN_HOOK_SCRIPT}" `,
+	`/${INSTALLED_DISPATCHER}" `,
+	RELATIVE_RUN_HOOK_INVOCATION,
+	RELATIVE_CONSUMER_RUN_HOOK_INVOCATION,
+	RELATIVE_BUNDLE_INVOCATION,
+]
 // 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
 
-// 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 = value
-		.split(RUN_HOOK_INVOCATION)
-		.join(CONSUMER_RUN_HOOK_INVOCATION)
-		.split(PNPM_JOSH_PREFIX)
-		.join(BUNDLE_INVOCATION)
-
-	if (
-		!rewritten.includes(claude_plugin_config.MARKETPLACE_PATH) ||
-		rewritten.includes(MISSING_INSTALL_GUARD)
-	) {
-		return rewritten
-	}
+function install_guard(root: string): string {
+	const manifest = hook_launch.rooted_path(root, INSTALLED_MANIFEST)
+
+	return `if [ ! -f ${manifest} ]; then echo '${MISSING_INSTALL_NOTICE}' >&2; exit 0; fi; `
+}
+
+// What a command starts with ahead of its launch — a root prefix, an install guard — is taken off
+// before the rewrite, and the current guard put back after it, so a second pass never doubles either.
+function launch_part(command: string, root: string): string {
+	const prefix = ROOT_PREFIXES.find((candidate) => command.startsWith(candidate)) ?? ''
+	const launch = command.slice(prefix.length)
+	const guard = [RELATIVE_INSTALL_GUARD, install_guard(root)].find((candidate) =>
+		launch.startsWith(candidate),
+	)
+
+	return launch.slice(guard?.length ?? 0)
+}
+
+// Every launch shape becomes the installed launcher or dispatcher under `root`. No replacement contains
+// another's anchor, so the order does not matter and the whole rewrite is safe to run more than once.
+function rebased(launch: string, root: string): string {
+	const consumer_launch = `sh ${hook_launch.rooted_path(root, INSTALLED_LAUNCHER)} `
+	const bundle_launch = `node ${hook_launch.rooted_path(root, INSTALLED_DISPATCHER)} `
+	const replacements: ReadonlyArray<readonly [string, string]> = [
+		[`sh ${hook_launch.rooted_path(root, hook_launch.RUN_HOOK_SCRIPT)} `, consumer_launch],
+		[RELATIVE_CONSUMER_RUN_HOOK_INVOCATION, consumer_launch],
+		[RELATIVE_RUN_HOOK_INVOCATION, consumer_launch],
+		[RELATIVE_BUNDLE_INVOCATION, bundle_launch],
+		[PNPM_JOSH_PREFIX, bundle_launch],
+	]
+	let text = launch
+
+	for (const [from, to] of replacements) text = text.split(from).join(to)
+
+	return text
+}
+
+function rewrite_command(command: string, root: string): string {
+	const rewritten = rebased(launch_part(command, root), root)
 
-	return `${MISSING_INSTALL_GUARD}${rewritten}`
+	return rewritten.includes(PACKAGE_PATH) ? `${install_guard(root)}${rewritten}` : rewritten
 }
 
-// kit's own commands already start from the root (`hook-launch.ts`), and so does an already-rewritten
-// value. The prefix — the current one or an earlier one — is taken off before the rewrite and the
-// current one 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 {
-	const prefix = ROOT_PREFIXES.find((candidate) => value.startsWith(candidate)) ?? ''
+// The field holds the command JSON-escaped; it is rewritten as the shell reads it and escaped back,
+// and a command the rewrite leaves alone keeps its original text.
+function rewrite_command_value(value: string, root: string): string {
+	const command = JSON.parse(`"${value}"`) as string
+	const rewritten = rewrite_command(command, root)
 
-	return value.slice(prefix.length)
+	return rewritten === command ? value : JSON.stringify(rewritten).slice(1, -1)
 }
 
 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(without_root_prefix(value))
-		const should_select_root = is_codex || rewritten.includes(claude_plugin_config.MARKETPLACE_PATH)
-		const prefix = should_select_root ? PROJECT_ROOT_PREFIX : ''
+	const root = is_codex ? hook_launch.CODEX_ROOT : hook_launch.CLAUDE_ROOT
 
-		return `${open}${prefix}${rewritten}${close}`
-	})
+	return content.replaceAll(
+		COMMAND_FIELD,
+		(_match, open: string, value: string, close: string) =>
+			`${open}${rewrite_command_value(value, root)}${close}`,
+	)
 }
 
 // Rewrite copied Claude and Codex hook files only; kit's source files keep their live-source fallback.

package/scripts/init/hook-launch.ts

@@ -3,34 +3,36 @@
 // Each hook is pre-built to its own `dist/hooks/<name>.js`
 // (`scripts/build/build-hooks.ts`) and launched directly with `node`.
 //
-// **The command starts from the project root, never from wherever the session happens to be**.
-// Every path after the prefix is relative, so a hook fired from a subdirectory would otherwise miss its
-// script. Claude Code names the root in `CLAUDE_PROJECT_DIR`, so its hooks start no `git` to find it;
-// Codex runs a hook in the session's directory and names no root, so there the root is git's — asked
-// first without the git location variables a git hook leaks, since a relative or bare `GIT_DIR` read
-// from a subdirectory names the wrong work tree, and with them only when the checkout does not resolve
-// without them (its metadata lives outside the work tree). A lookup that fails ends the command before
-// the launcher (joshuafolkken/kit#4187). Inside one of Claude Code's own worktrees `CLAUDE_PROJECT_DIR`
-// still names the main checkout, so the prefix exports where the hook was launched as `JOSH_HOOK_CWD`
-// and the launcher moves the hook's working directory into that worktree (joshuafolkken/kit#4617).
-//
-// **Everything after the root is one script** (`scripts/hooks/run-hook.sh`): the git location
-// variables a git hook exports, the bundle-ready gate and the live-source fallback live there once, so
-// each hook command names only its hook. The consumer rewrite (`hook-command-rewrite.ts`) keeps this
-// prefix, so both sides stay one mechanism for Claude Code and Codex alike.
-
-import { GIT_LOCATION_VARIABLES } from '#scripts/git/git-location-environment'
+// **The command only names the launcher by its absolute path**; everything else — the move to the
+// project root, the launch directory a worktree hook needs, the git location variables a git hook
+// leaks — lives once in `scripts/hooks/run-hook.sh`. Claude Code names the root in
+// `CLAUDE_PROJECT_DIR`, so its hooks start no `git` to find the launcher. Codex runs a hook in the
+// session's directory and names no root, so `.codex/hooks.json` asks git — first without the two
+// variables that place a checkout, since a relative or foreign `GIT_DIR` read from a subdirectory names
+// the wrong work tree, and with them only when the checkout does not resolve without them (its metadata
+// lives outside the work tree). The lookup is scoped to its subshell; the hook's own environment is the
+// launcher's to clear.
 
 const HOOK_DIST_DIR = 'dist/hooks'
 const RUN_HOOK_SCRIPT = 'scripts/hooks/run-hook.sh'
 const ROOT_LOOKUP = 'git rev-parse --show-toplevel'
-const CODEX_ROOT = `$( (unset ${GIT_LOCATION_VARIABLES.join(' ')}; ${ROOT_LOOKUP} 2>/dev/null) || ${ROOT_LOOKUP})`
-const PROJECT_ROOT_PREFIX = `export JOSH_HOOK_CWD="$PWD" && project_root="\${CLAUDE_PROJECT_DIR:-${CODEX_ROOT}}" && cd "$project_root" && `
+const CLAUDE_ROOT = '$CLAUDE_PROJECT_DIR'
+const CODEX_ROOT = `$( (unset GIT_DIR GIT_WORK_TREE; ${ROOT_LOOKUP} 2>/dev/null) || ${ROOT_LOOKUP})`
+
+// A path under `root` as a hook command names it: quoted, so a root with spaces stays one word.
+function rooted_path(root: string, relative_path: string): string {
+	return `"${root}/${relative_path}"`
+}
 
 // `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}`
+function hook_launch_command(name: string, root = CLAUDE_ROOT): string {
+	return `sh ${rooted_path(root, RUN_HOOK_SCRIPT)} ${name}`
+}
+
+// The same command as Codex runs it, which names no root.
+function codex_command(command: string): string {
+	return command.split(`"${CLAUDE_ROOT}/`).join(`"${CODEX_ROOT}/`)
 }
 
 // The josh subcommand the launcher falls back to for hook `name`: its first `-` becomes `:`
@@ -41,10 +43,13 @@ function fallback_command(name: string): string {
 }
 
 const hook_launch = {
+	CLAUDE_ROOT,
+	codex_command,
+	CODEX_ROOT,
 	fallback_command,
 	HOOK_DIST_DIR,
 	hook_launch_command,
-	PROJECT_ROOT_PREFIX,
+	rooted_path,
 	RUN_HOOK_SCRIPT,
 }
 

package/scripts/init/init-ai-copy.ts

@@ -15,6 +15,7 @@ import { transform_copied_content } from './init-copy-content'
 import { init_logic } from './init-logic'
 import { package_path, PROJECT_ROOT } from './init-paths'
 import { init_sonar } from './init-sonar'
+import { npm_publish_files } from './npm-publish-files'
 import type { ProjectShape } from './project-profile'
 import { security_policy } from './security-policy'
 
@@ -59,8 +60,8 @@ const BASIC_GITHUB_MAPPINGS = [
 	{ src: RELEASE_CONFIG, dest: RELEASE_CONFIG },
 ]
 
-// Whether the existing file is a workflow that carries no header. A read failure answers "no": the
-// point is to warn, and a warning is not worth failing a command that used to open nothing.
+// Whether the existing file is a workflow that carries no header. A read failure answers "no": a
+// diagnostic warning must not fail the command it accompanies.
 function did_read_unstamped(destination_path: string): boolean {
 	try {
 		return !managed_marker_logic.is_marked(readFileSync(destination_path, 'utf8'))
@@ -124,7 +125,9 @@ function did_skip_copy_if_absent(
 function read_workspace_template(source_path: string, destination_path: string): string {
 	const npmrc = file_reader.read_file_or_empty(path.join(path.dirname(destination_path), '.npmrc'))
 
-	return init_logic.carry_npmrc_settings(readFileSync(source_path, 'utf8'), npmrc)
+	const distributed = init_logic.drop_kit_only_regions(readFileSync(source_path, 'utf8'))
+
+	return init_logic.carry_npmrc_settings(distributed, npmrc)
 }
 
 function merge_existing_workspace_yaml(source_path: string, destination_path: string): void {
@@ -343,6 +346,12 @@ function ai_files(shape?: ProjectShape): ReadonlyArray<string> {
 	return files.filter((filename) => should_copy_ai_file(filename, shape))
 }
 
+// What `josh init` and `josh sync` copy: the static set and, for a repository that publishes to npm,
+// the publish workflow (`npm-publish-files.ts`).
+function copied_files(shape?: ProjectShape): ReadonlyArray<string> {
+	return [...ai_files(shape), ...npm_publish_files.files(shape)]
+}
+
 type FileMappings = ReturnType<typeof init_logic.get_ai_copy_file_mappings>
 
 function ai_file_mappings(shape?: ProjectShape): FileMappings {
@@ -372,7 +381,7 @@ function report_sync_hint(has_skips: boolean, shape?: ProjectShape): void {
 
 function run_ai_copies(shape?: ProjectShape): string | undefined {
 	const did_skip_claude_md = did_skip_claude_md_import(shape)
-	const file_skips = ai_files(shape).map((filename) => did_skip_ai_file_copy(filename, shape))
+	const file_skips = copied_files(shape).map((filename) => did_skip_ai_file_copy(filename, shape))
 	const mapping_skips = ai_mapping_skips(shape)
 	const directory_skips = init_logic
 		.get_ai_copy_directories()
@@ -396,6 +405,7 @@ const init_ai_copy = {
 	workspace_content,
 	run_ai_copies,
 	ai_files,
+	copied_files,
 	ai_file_source,
 	ai_file_mappings,
 	ensure_basic_claude_md,

package/scripts/init/init-bootstrap.ts

@@ -13,6 +13,9 @@ const NODE_MODULES = 'node_modules'
 // The basic template lists exactly the build scripts kit's own dependency tree carries, which is
 // what installing kit alone needs approved.
 const KIT_BUILDS_TEMPLATE = 'templates/pnpm-workspace.basic.yaml'
+const WORKSPACE_FILE = 'pnpm-workspace.yaml'
+const NPMRC_FILE = '.npmrc'
+const RELEASE_AGE_KEY = 'minimumReleaseAge'
 const HANDOFF_FAILURE = 'josh init from the project-installed kit failed — see the output above'
 // Set on the handed-off run, so a kit that still does not find itself installed in the project — pnpm
 // put it somewhere else — stops instead of installing and handing off again without end.
@@ -28,11 +31,8 @@ function real_directory(directory: string): string | undefined {
 	return existsSync(directory) ? realpathSync(directory) : undefined
 }
 
-// A `pnpm dlx` (or global) run executes whatever kit its cache held, which may be days behind the
-// registry — and `init` pins the kit it runs as, so a stale cache used to leave its version and its
-// templates in the project for good. Only the kit the project itself installs
-// does the setup. Compared by real path, so a global virtual store shared with the project still
-// reads as the project's own kit.
+// Only the project's installed kit performs setup so a stale dlx/global cache cannot pin stale
+// templates and a stale version. Real-path comparison recognizes a shared global virtual store.
 function is_project_kit(package_directory: string, project_root: string): boolean {
 	const installed = real_directory(path.join(project_root, NODE_MODULES, KIT_PACKAGE_NAME))
 
@@ -53,8 +53,9 @@ function has_kit_dependency(project_root: string): boolean {
 	return names.includes(KIT_PACKAGE_NAME)
 }
 
-// A project that already lists kit keeps the version it chose; otherwise pnpm picks it, under the
-// project's own `minimumReleaseAge`, so the version installed is never the cache's decision.
+// A project that already lists kit keeps the version it chose; otherwise pnpm picks it under the
+// `minimumReleaseAge` `ensure_release_age` wrote first, so the version installed is never the cache's
+// decision — a kit published inside the wait leaves the one before it installed.
 function kit_install_step(has_kit: boolean, template: string): InstallStep {
 	if (has_kit) return { label: 'pnpm install', command: 'pnpm', args: ['install'] }
 	const args = ['add', '-D', ...kit_build_flags(template), KIT_PACKAGE_NAME]
@@ -62,6 +63,10 @@ function kit_install_step(has_kit: boolean, template: string): InstallStep {
 	return { label: `pnpm ${args.join(' ')}`, command: 'pnpm', args }
 }
 
+function install_failure(install: InstallStep): string {
+	return `${install.label} failed — ${init_install.TOO_NEW_DEPENDENCY_HINT}`
+}
+
 function handoff_step(args: ReadonlyArray<string>): InstallStep {
 	const handoff_args = ['exec', 'josh', 'init', ...project_profile.with_legacy_profile_names(args)]
 
@@ -83,6 +88,32 @@ function ensure_project_manifest(project_root: string): void {
 	file_content.write_contained(manifest_path, init_basic.initial_manifest())
 }
 
+function read_optional(file: string): string {
+	return existsSync(file) ? readFileSync(file, 'utf8') : ''
+}
+
+// The template's wait, with a project's own `.npmrc` value carried the way `josh init` carries it,
+// so the later merge finds the key already holding the value it would have written.
+function release_age_block(project_root: string, template: string): string {
+	const block = `${init_logic_workspace.extract_yaml_block(template, RELEASE_AGE_KEY)}\n`
+	const npmrc = read_optional(path.join(project_root, NPMRC_FILE))
+
+	return init_logic_workspace.carry_npmrc_settings(block, npmrc)
+}
+
+// `josh init` writes the wait only after kit is installed, so without it here the first install
+// resolves kit's whole tree with no wait and the lockfile pins versions later installs refuse (#7200).
+function ensure_release_age(project_root: string, template: string): void {
+	const workspace_path = path.join(project_root, WORKSPACE_FILE)
+	const existing = read_optional(workspace_path)
+	const block = release_age_block(project_root, template)
+	const merged = init_logic_workspace.merge_workspace_yaml(existing, block)
+
+	if (merged === existing) return
+
+	file_content.write_contained(workspace_path, merged)
+}
+
 function is_handed_off(): boolean {
 	return process.env[HANDOFF_ENV] !== undefined
 }
@@ -99,7 +130,8 @@ function hand_off(
 	const install = kit_install_step(has_kit_dependency(project_root), template)
 
 	ensure_project_manifest(project_root)
-	if (!init_install.did_step_succeed(install, project_root)) return `${install.label} failed`
+	ensure_release_age(project_root, template)
+	if (!init_install.did_step_succeed(install, project_root)) return install_failure(install)
 	if (!init_install.did_step_succeed(handoff_step(args), project_root)) return HANDOFF_FAILURE
 
 	return undefined

package/scripts/init/init-copy-content.ts

@@ -23,8 +23,8 @@ import { security_policy } from './security-policy'
  *
  * The consumer's `.claude/settings.json` gets three further passes. The keys kit sets only for its
  * own sessions are removed (see claude-kit-only-settings.ts). The kit plugin's marketplace and
- * `enabledPlugins` declaration is injected, because the skills that used to be copied now ship as the
- * `kit` plugin and load from that declaration. And its hook commands are
+ * `enabledPlugins` declaration is injected, because skills ship as the `kit` plugin and load from
+ * that declaration. And its hook commands are
  * rewritten from `pnpm josh` to the published bundle invoked directly with node,
  * so a consumer's guarded call does not pay a `pnpm` launch it never needed.
  * Keeping both on this one function is the same guarantee as the workflow passes — a copy path that

package/scripts/init/init-install.ts

@@ -19,9 +19,16 @@ const FORMAT_STEP: InstallStep = {
 	command: 'pnpm',
 	args: ['exec', 'josh', 'format'],
 }
+// A lockfile written before the project had `minimumReleaseAge` can pin a version published inside
+// the wait, which every later install refuses; only resolving again drops it (#7200).
+const TOO_NEW_DEPENDENCY_HINT = [
+	'If pnpm refused a dependency published inside minimumReleaseAge, the lockfile pins a version',
+	'newer than the wait allows: delete pnpm-lock.yaml and run pnpm install to resolve again.',
+].join(' ')
 const INSTALL_FAILURE = [
 	`${INSTALL_STEP.label} failed — fix the cause above,`,
-	`then run it manually: ${INSTALL_STEP.label} && ${FORMAT_STEP.label}`,
+	`then run it manually: ${INSTALL_STEP.label} && ${FORMAT_STEP.label}.`,
+	TOO_NEW_DEPENDENCY_HINT,
 ].join(' ')
 const FORMAT_WARNING = [
 	`  ⚠ ${FORMAT_STEP.label} left problems it could not fix in the project's own files —`,
@@ -65,6 +72,7 @@ function run_post_init_steps(project_root: string): string | undefined {
 const init_install = {
 	NO_INSTALL_FLAG,
 	INSTALL_STEP,
+	TOO_NEW_DEPENDENCY_HINT,
 	FORMAT_STEP,
 	split_install_flag,
 	did_step_succeed,

package/scripts/init/init-logic-deploy-vps.ts

@@ -1,3 +1,4 @@
+import { pnpm_installer } from '#scripts/lib/pnpm-installer'
 import semver from 'semver'
 
 const PNPM_INSTALL_PATTERN = /npm install -g pnpm@\d[\d.]{0,19}/gu
@@ -8,6 +9,7 @@ const OLD_PNPM_CHECK_PATTERN =
 const OLD_MAJOR_LINE_PATTERN =
 	/^[ \t]*PNPM_MAJOR=\$\(pnpm --version 2>\/dev\/null \| cut -d\. -f1 \|\| echo "0"\)\n/mu
 const VERSION_CHECK_MARKER = '[ "$PNPM_MINOR" -lt 1 ]'
+const UNVERIFIED_INSTALLER = /curl -fsSL https:\/\/get\.pnpm\.io\/install\.sh \| sh -/gu
 
 function replace_outdated_install(command: string): string {
 	const version = command.slice('npm install -g pnpm@'.length)
@@ -27,9 +29,9 @@ function build_version_check(indent: string): string {
 }
 
 function patch_deploy_vps_pnpm(content: string): string {
-	const with_pnpm12 = content.replaceAll(PNPM_INSTALL_PATTERN, (command) =>
-		replace_outdated_install(command),
-	)
+	const with_pnpm12 = content
+		.replaceAll(UNVERIFIED_INSTALLER, () => pnpm_installer.command())
+		.replaceAll(PNPM_INSTALL_PATTERN, (command) => replace_outdated_install(command))
 
 	if (with_pnpm12.includes(VERSION_CHECK_MARKER) || !OLD_PNPM_CHECK_PATTERN.test(with_pnpm12)) {
 		return with_pnpm12