@joshuafolkken/kit 1.921.0 → 1.929.0

package/playwright.config.ts

@@ -1,5 +1,6 @@
 import { environment_flags } from '@joshuafolkken/kit/env'
 import { ports } from '@joshuafolkken/kit/ports'
+import { web_server } from '@joshuafolkken/kit/web-server'
 import { defineConfig, devices, type ReporterDescription } from '@playwright/test'
 
 // Both ports come from kit's single definition (`@joshuafolkken/kit/ports`), offset by the personal
@@ -17,7 +18,7 @@ import { defineConfig, devices, type ReporterDescription } from '@playwright/tes
 // the file, and a project with no `.env` is untouched.
 //
 // The working directory is the anchor, and the loader ascends from it to the project root — the
-// same root `pnpm run` hands the `webServer` command, so both sides name one file from anywhere
+// same root `node --run` hands the `webServer` command, so both sides name one file from anywhere
 // inside the project. The one layout that escapes that is a run whose working directory sits in a
 // *different* package from this config, as `playwright test --config ../../playwright.config.ts`
 // does in a workspace: Playwright would default `webServer.cwd` to this file's directory while the
@@ -31,13 +32,6 @@ const PREVIEW_PORT = ports.resolve_preview_port()
 
 const CI_TIMEOUT = 120_000
 const LOCAL_TIMEOUT = 30_000
-// pnpm 11.27.1+ places a script it runs without a controlling terminal in its own process group, so
-// Playwright's default teardown — SIGKILL to the webServer's group — no longer reaches the `vite dev`
-// / `preview` child: it survives holding Playwright's stdio pipes open, and Playwright blocks forever
-// on the `close` event (#2386). SIGTERM, unlike SIGKILL, is relayed by that pnpm to the child, so a
-// graceful shutdown lets the server exit and the pipes close. The timeout must stay well above the
-// observed ~40ms shutdown, or Playwright falls back to killProcess() (SIGKILL) and the hang returns.
-const SHUTDOWN_TIMEOUT = 10_000
 const CI_TEST_TIMEOUT = 30_000
 const ACTION_TIMEOUT = 10_000
 const NAV_TIMEOUT = 30_000
@@ -74,7 +68,7 @@ const IS_CI = environment_flags.is_ci_enabled(process.env['CI'])
 // run whose report is unreachable unless the developer already knows `playwright show-report`.
 // (`CI/1` in the Playwright user agent and the MCP headless force share the same root cause.)
 // Deleting the variable once this config has judged the run local is what makes every downstream
-// reader agree with that verdict, the `pnpm run dev` child process included: leaving `CI=0` set for
+// reader agree with that verdict, the `dev` script's child process included: leaving `CI=0` set for
 // the child would only re-introduce the same bare-truthiness bug one process down. The guard is
 // what keeps this safe — a real provider value such as `CI=woodpecker` is never touched, and the
 // deletion cannot fire on the CI branch.
@@ -91,24 +85,22 @@ if (!IS_CI) delete process.env['CI']
 // application; a seed reduces how often a foreign server is on the port at all.
 const IS_REUSE_ENABLED = environment_flags.is_flag_enabled(process.env['PLAYWRIGHT_REUSE_SERVER'])
 
-// Both branches share one shutdown policy — see SHUTDOWN_TIMEOUT for why SIGTERM rather than the
-// SIGKILL default. `as const` keeps the signal a literal so it satisfies Playwright's signal union.
-const GRACEFUL_SHUTDOWN = { signal: 'SIGTERM', timeout: SHUTDOWN_TIMEOUT } as const
-
+// The scripts run through `node --run` rather than `pnpm run`, so the server stays in the process
+// group Playwright signals on teardown and its default SIGKILL reaches it directly — no package
+// manager relays the signal, and no graceful-shutdown timeout has to be tuned around one (#2392).
+// Each script's `pre` hook is chained in explicitly, since `node --run` does not run it.
 const web_server_config = IS_CI
 	? {
-			command: 'pnpm run build && pnpm run preview',
+			command: web_server.script_command(['build', 'preview']),
 			port: PREVIEW_PORT,
 			timeout: CI_TIMEOUT,
 			reuseExistingServer: IS_REUSE_ENABLED,
-			gracefulShutdown: GRACEFUL_SHUTDOWN,
 		}
 	: {
-			command: 'pnpm run dev',
+			command: web_server.script_command(['dev']),
 			port: DEV_PORT,
 			timeout: LOCAL_TIMEOUT,
 			reuseExistingServer: IS_REUSE_ENABLED,
-			gracefulShutdown: GRACEFUL_SHUTDOWN,
 		}
 
 const env_config: EnvConfig = IS_CI

package/ports/index.d.ts

@@ -7,6 +7,7 @@ declare const PROJECT_ENVIRONMENT_KEYS: ReadonlySet<string>
 
 declare const ports: {
 	load_environment_file: (directory?: string) => boolean
+	resolve_project_directory: (directory: string) => string
 	resolve_seed: (environment?: PortEnvironment) => number
 	resolve_lane: (environment?: PortEnvironment) => number
 	resolve_development_port: (environment?: PortEnvironment) => number

package/ports/index.js

@@ -247,6 +247,7 @@ function load_environment_file(directory = process.cwd()) {
 
 const ports = {
 	load_environment_file,
+	resolve_project_directory,
 	resolve_seed,
 	resolve_lane,
 	resolve_development_port,

package/ports/web-server.d.ts

@@ -0,0 +1,5 @@
+declare const web_server: {
+	script_command: (names: Array<string>, directory?: string) => string
+}
+
+export { web_server }

package/ports/web-server.js

@@ -0,0 +1,73 @@
+// The command Playwright's `webServer` runs, built so no package manager stands between Playwright
+// and the server it starts.
+//
+// Playwright spawns the command detached and tears it down by signalling that process group. pnpm
+// 11.27.1+ moves a script it runs without a controlling terminal into a group of its own, so the
+// teardown reached pnpm alone and the dev / preview server survived holding Playwright's stdio pipes
+// open — a hang #2386 patched by relying on pnpm to relay SIGTERM. `node --run` executes the same
+// `package.json` script in the caller's process group, so the teardown signal reaches the server
+// itself and there is no relay left to depend on (#2392).
+//
+// The script names stay the interface rather than a hard-coded `vite` invocation: a consumer's
+// `preview` is not necessarily `vite preview` (wrangler serves the Cloudflare build), and each script
+// resolves its own port through `josh port`. What `node --run` does not do is run `pre<name>` hooks,
+// which a consumer can rely on — a `prepreview` applying local database migrations, say — so the hook
+// is chained explicitly here instead of being dropped without a word. `post<name>` is not: a server
+// script never ends on its own, so its post hook would never have run under pnpm either.
+import { existsSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+import { ports } from './index.js'
+
+const PACKAGE_FILE_NAME = 'package.json'
+const PRE_HOOK_PREFIX = 'pre'
+const STEP_SEPARATOR = ' && '
+
+/**
+ * The `scripts` of the project root's `package.json` — the same file `node --run` resolves from the
+ * working directory — or an empty record when there is none.
+ *
+ * @param {string} directory
+ * @returns {Record<string, unknown>}
+ */
+function read_scripts(directory) {
+	const file = path.join(ports.resolve_project_directory(directory), PACKAGE_FILE_NAME)
+	if (!existsSync(file)) return {}
+
+	const { scripts } = JSON.parse(readFileSync(file, 'utf8'))
+
+	return typeof scripts === 'object' && scripts !== null ? scripts : {}
+}
+
+/**
+ * @param {string} name
+ * @param {Record<string, unknown>} scripts
+ * @returns {string[]}
+ */
+function steps_for(name, scripts) {
+	const hook = `${PRE_HOOK_PREFIX}${name}`
+
+	return Object.hasOwn(scripts, hook) ? [hook, name] : [name]
+}
+
+/**
+ * Chain the named `package.json` scripts, each preceded by its `pre` hook when the project defines
+ * one, into a single shell command run through `node --run`.
+ *
+ * @param {string[]} names
+ * @param {string} [directory]
+ * @returns {string}
+ */
+function script_command(names, directory = process.cwd()) {
+	const scripts = read_scripts(directory)
+
+	return names
+		.flatMap((name) => steps_for(name, scripts))
+		.map((step) => `node --run ${step}`)
+		.join(STEP_SEPARATOR)
+}
+
+const web_server = {
+	script_command,
+}
+
+export { web_server }

package/scripts/agent/agent-role-profile.ts

@@ -201,6 +201,16 @@ function resolve_provider(environment: AgentEnvironment = process.env): Provider
 	return detected_provider(environment) ?? handed_provider(environment)
 }
 
+// Whether this session is woken when a background command it started completes
+// (joshuafolkken/kit#2653). Claude Code re-invokes the session at the completion; a Codex session is not
+// re-invoked, so a parent there can only wait by polling, each poll a model call over its whole context.
+// Only a resolved Codex session answers no — an unresolved one keeps the behavior it had before.
+function has_completion_callback(environment: AgentEnvironment = process.env): boolean {
+	const selected = resolve_provider(environment)
+
+	return selected.kind !== 'provider' || selected.provider !== OPENAI_PROVIDER
+}
+
 // The mark a detached launch sets on its child: the provider this session resolved, or nothing when it
 // resolved none — the child then fails the same way this session would have.
 function handoff_environment(
@@ -309,6 +319,7 @@ const agent_role_profile = {
 	WORKER,
 	describe,
 	handoff_environment,
+	has_completion_callback,
 	is_safe_value,
 	parse,
 	phase_effort,

package/scripts/gate/project-checks.ts

@@ -102,6 +102,28 @@ function type_check_skip_reason(directory: string): string | undefined {
 	return undefined
 }
 
+// Shared by `josh lint` and `josh format`, so a static project without Web files — a Python or Rust
+// project, which `josh init` gives no Prettier — is skipped for the same reason by both
+// (joshuafolkken/kit#2606).
+function prettier_skip_reason(directory: string): string | undefined {
+	if (!is_static(directory)) return undefined
+	if (!has_files(directory, WEB_FILES)) return 'no HTML, CSS or JavaScript files were found'
+	if (!has_bin(directory, 'prettier')) return 'prettier is not installed'
+
+	return undefined
+}
+
+// Shared by `josh lint` and `josh format`, so a static project without ESLint is skipped for the
+// same reason by both (joshuafolkken/kit#2693).
+function eslint_skip_reason(directory: string): string | undefined {
+	if (!is_static(directory)) return undefined
+	if (!has_files(directory, SCRIPT_FILES)) return 'no JavaScript or TypeScript files were found'
+	if (!has_config(directory, ESLINT_CONFIGS)) return 'no ESLint configuration was found'
+	if (!has_bin(directory, 'eslint')) return 'eslint is not installed'
+
+	return undefined
+}
+
 const project_checks = {
 	CSPELL_CONFIGS,
 	ESLINT_CONFIGS,
@@ -109,10 +131,12 @@ const project_checks = {
 	TYPE_CONFIGS,
 	TYPE_FILES,
 	WEB_FILES,
+	eslint_skip_reason,
 	has_bin,
 	has_config,
 	has_files,
 	is_static,
+	prettier_skip_reason,
 	project_root,
 	skip_notice,
 	type_check_skip_reason,

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

@@ -28,7 +28,13 @@ const STATIC_AI_FILES = [
 	GIT_ATTRIBUTES,
 	CODE_OF_CONDUCT,
 	SECURITY_MD,
+	WORKSPACE_YAML,
 ]
+// A static project gets its own template for these, not kit's development copy (joshuafolkken/kit#2693).
+const STATIC_SOURCES: Readonly<Record<string, string>> = {
+	[PRETTIER_IGNORE]: 'templates/prettierignore.static',
+	[WORKSPACE_YAML]: 'templates/pnpm-workspace.static.yaml',
+}
 const GITHUB_FILES = new Set([CODE_OF_CONDUCT, SECURITY_MD])
 const STATIC_POINTER_MAPPING = { src: 'templates/cursorrules.static', dest: '.cursorrules' }
 const PULL_REQUEST_TEMPLATE = '.github/pull_request_template.md'
@@ -112,11 +118,8 @@ function did_skip_workspace_yaml_copy(source_path: string, destination_path: str
 }
 
 function did_skip_ai_file_copy(filename: string, shape?: ProjectShape): boolean {
-	const source_path = package_path(
-		filename === PRETTIER_IGNORE && shape?.profile === 'static'
-			? 'templates/prettierignore.static'
-			: filename,
-	)
+	const static_source = shape?.profile === 'static' ? STATIC_SOURCES[filename] : undefined
+	const source_path = package_path(static_source ?? filename)
 	const destination_path = path.join(PROJECT_ROOT, filename)
 
 	if (filename === WORKSPACE_YAML) {

package/scripts/init/init-logic-workspace.ts

@@ -42,16 +42,49 @@ function remove_deprecated_yaml_keys(content: string): string {
 	return `${result.trimEnd()}\n`
 }
 
+// pnpm 11+ writes this placeholder into `allowBuilds` for every build script it ignored, and fails
+// every later install until it is answered. `pnpm add -D @joshuafolkken/kit` before `josh init`
+// leaves one for esbuild, and the key-level merge below keeps an existing `allowBuilds` whole, so a
+// placeholder the template decides is answered here (joshuafolkken/kit#2693).
+const BUILD_PLACEHOLDER_PATTERN = /^([ \t]+)([^\s:#][^:#]*): set this to true or false$/gmu
+const TEMPLATE_BUILD_PATTERN = /^[ \t]+(?<key>[^\s:#][^:#]*):[ \t]*(?<value>true|false)\b/u
+
+function unquote(key: string): string {
+	return key.trim().replaceAll(/^['"]|['"]$/gu, '')
+}
+
+function template_build_values(template: string): Map<string, string> {
+	const lines = extract_yaml_block(template, 'allowBuilds').split('\n')
+
+	return new Map(
+		lines.flatMap((line) => {
+			const { key, value } = TEMPLATE_BUILD_PATTERN.exec(line)?.groups ?? {}
+
+			return key && value ? [[unquote(key), value] as const] : []
+		}),
+	)
+}
+
+function answer_build_placeholders(existing: string, template: string): string {
+	const values = template_build_values(template)
+
+	return existing.replaceAll(BUILD_PLACEHOLDER_PATTERN, (line, indent: string, key: string) => {
+		const value = values.get(unquote(key))
+
+		return value === undefined ? line : `${indent}${key}: ${value}`
+	})
+}
+
 function merge_workspace_yaml(existing: string, template: string): string {
 	if (!existing.trim()) return template
 	const normalized = existing.endsWith('\n') ? existing : `${existing}\n`
-	const without_deprecated = remove_deprecated_yaml_keys(normalized)
-	if (!without_deprecated.trim()) return template
-	const existing_keys = new Set(extract_yaml_top_level_keys(without_deprecated))
+	const cleaned = answer_build_placeholders(remove_deprecated_yaml_keys(normalized), template)
+	if (!cleaned.trim()) return template
+	const existing_keys = new Set(extract_yaml_top_level_keys(cleaned))
 	const new_keys = extract_yaml_top_level_keys(template).filter((k) => !existing_keys.has(k))
-	if (new_keys.length === 0) return without_deprecated
+	if (new_keys.length === 0) return cleaned
 
-	return append_user_blocks(without_deprecated, new_keys, template)
+	return append_user_blocks(cleaned, new_keys, template)
 }
 
 const init_logic_workspace = { merge_workspace_yaml }

package/scripts/init/init-logic.ts

@@ -451,6 +451,7 @@ const init_logic = {
 	strip_kit_only_vscode_settings,
 	strip_kit_only_vscode_settings_content,
 	VSCODE_EXTENSIONS_FILENAME,
+	SAFE_CHAIN_CMD,
 	GUARDED_LEFTHOOK_CMD,
 	upgrade_prepare_lefthook_warning,
 	get_npmrc_lines,

package/scripts/init/init-static.ts

@@ -36,7 +36,10 @@ function merge_static_manifest(
 	versions: StaticVersions,
 ): string {
 	const with_profile = with_recorded_profile(content, shape.profile)
-	const with_script = init_logic.merge_package_scripts(with_profile, { josh: 'josh' })
+	const with_script = init_logic.merge_package_scripts(with_profile, {
+		preinstall: init_logic.SAFE_CHAIN_CMD,
+		josh: 'josh',
+	})
 	const with_kit = init_logic.merge_development_dependencies(with_script, {
 		[KIT_PACKAGE_NAME]: versions.kit,
 	})

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 { KIT_PACKAGE_NAME } from '#scripts/version/kit-descriptor'
 import { execaSync } from 'execa'
 
 type ProjectProfile = 'static' | 'node'
@@ -52,10 +53,6 @@ function read_manifest(root: string): Record<string, unknown> | undefined {
 	return parsed as Record<string, unknown>
 }
 
-function has_entries(value: unknown): boolean {
-	return typeof value === 'object' && value !== null && Object.keys(value).length > 0
-}
-
 function is_record(value: unknown): value is Record<string, unknown> {
 	return typeof value === 'object' && value !== null && !Array.isArray(value)
 }
@@ -70,8 +67,20 @@ function has_build_script(value: unknown): boolean {
 	return 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 static
+// (joshuafolkken/kit#2693).
+function has_project_dependencies(value: unknown): boolean {
+	if (!is_record(value)) return false
+
+	return Object.keys(value).some((name) => name !== KIT_PACKAGE_NAME)
+}
+
 function inferred_profile(manifest: Record<string, unknown>): ProfileResult {
-	if (has_entries(manifest['dependencies']) || has_entries(manifest['devDependencies'])) {
+	if (
+		has_project_dependencies(manifest['dependencies']) ||
+		has_project_dependencies(manifest['devDependencies'])
+	) {
 		return { profile: 'node', reason: 'package dependencies' }
 	}
 

package/scripts/josh/josh-commands-development.ts

@@ -1,10 +1,4 @@
-import {
-	ESLINT_CACHE_FLAGS,
-	GATE_COMMAND,
-	PE,
-	TS_CACHE_FLAGS,
-	type CommandEntry,
-} from './josh-command-types'
+import { GATE_COMMAND, PE, TS_CACHE_FLAGS, type CommandEntry } from './josh-command-types'
 
 const FILE_ARGUMENTS = '[files...]'
 const REQUIRED_FILE_ARGUMENTS = '<files...>'
@@ -66,14 +60,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		reference: ['', 'developer', ['none']],
 	},
 	format: {
-		// prettier first here, unlike `format:edited`, and deliberately: `eslint --fix` exits 1
-		// whenever a non-autofixable error remains, so putting it first behind `&&` would mean one
-		// unused variable anywhere in the tree stops prettier from running at all.
-		shell: [
-			'sh',
-			'-c',
-			`pnpm exec prettier --write . && pnpm exec eslint . --fix ${ESLINT_CACHE_FLAGS.join(' ')}`,
-		],
+		script: 'scripts/lint/format.ts',
 		description: 'Format code with prettier and eslint',
 		category: 'Development',
 		reference: ['', 'developer', ['files', 'processes']],

package/scripts/lint/format.ts

@@ -0,0 +1,68 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { project_checks } from '#scripts/gate/project-checks'
+import { ESLINT_CACHE_FLAGS } from '#scripts/josh/josh-command-types'
+import { composite_arguments, USAGE_ERROR_EXIT_CODE } from '#scripts/josh/josh-composite-arguments'
+import { execa } from 'execa'
+
+const COMMAND_NAME = 'format'
+const ARGV_OFFSET = 2
+const FAIL_EXIT_CODE = 1
+const PRETTIER_ARGS = ['exec', 'prettier', '--write', '.'] as const
+const ESLINT_FIX_ARGS = ['exec', 'eslint', '.', '--fix', ...ESLINT_CACHE_FLAGS] as const
+
+async function run_step(args: ReadonlyArray<string>, directory: string): Promise<number> {
+	const result = await execa('pnpm', args, { cwd: directory, stdio: 'inherit', reject: false })
+
+	return result.exitCode ?? FAIL_EXIT_CODE
+}
+
+// prettier first, deliberately: `eslint --fix` exits 1 whenever a non-autofixable error remains, so
+// putting it first would mean one unused variable anywhere in the tree stops prettier from running.
+// A static project without Prettier or ESLint is skipped with the same reason `josh lint` prints
+// (joshuafolkken/kit#2693, joshuafolkken/kit#2606).
+async function run_unless_skipped(
+	check: string,
+	reason: string | undefined,
+	args: ReadonlyArray<string>,
+	directory: string,
+): Promise<number> {
+	if (reason === undefined) return await run_step(args, directory)
+	console.info(project_checks.skip_notice(check, reason))
+
+	return 0
+}
+
+async function run_format(directory: string): Promise<number> {
+	const prettier_reason = project_checks.prettier_skip_reason(directory)
+	const prettier_exit_code = await run_unless_skipped(
+		'prettier',
+		prettier_reason,
+		PRETTIER_ARGS,
+		directory,
+	)
+	if (prettier_exit_code !== 0) return prettier_exit_code
+	const eslint_reason = project_checks.eslint_skip_reason(directory)
+
+	return await run_unless_skipped('eslint', eslint_reason, ESLINT_FIX_ARGS, directory)
+}
+
+// The argument refusal survives leaving the `sh -c` composite shape: both tools run over the whole
+// tree, so a path passed here would be silently discarded and every file rewritten instead.
+async function run(argv: ReadonlyArray<string>, directory: string): Promise<number> {
+	if (argv.length > 0) {
+		console.error(composite_arguments.format_rejection(COMMAND_NAME, []))
+
+		return USAGE_ERROR_EXIT_CODE
+	}
+
+	return await run_format(directory)
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	process.exitCode = await run(process.argv.slice(ARGV_OFFSET), process.cwd())
+}
+
+const format = { run, run_format }
+
+export { ESLINT_FIX_ARGS, format }

package/scripts/lint/lint-parallel.ts

@@ -35,29 +35,15 @@ function skipped(check: string, reason: string): BufferedProcessResult {
 }
 
 async function run_static_prettier(directory: string): Promise<BufferedProcessResult> {
-	if (!project_checks.has_files(directory, project_checks.WEB_FILES)) {
-		return skipped('prettier', 'no HTML, CSS or JavaScript files were found')
-	}
-
-	if (!project_checks.has_bin(directory, 'prettier')) {
-		return skipped('prettier', 'prettier is not installed')
-	}
+	const reason = project_checks.prettier_skip_reason(directory)
+	if (reason !== undefined) return skipped('prettier', reason)
 
 	return await buffered_process.run_buffered_process(PRETTIER_ARGS)
 }
 
 async function run_static_eslint(directory: string): Promise<BufferedProcessResult> {
-	if (!project_checks.has_files(directory, project_checks.SCRIPT_FILES)) {
-		return skipped('eslint', 'no JavaScript or TypeScript files were found')
-	}
-
-	if (!project_checks.has_config(directory, project_checks.ESLINT_CONFIGS)) {
-		return skipped('eslint', 'no ESLint configuration was found')
-	}
-
-	if (!project_checks.has_bin(directory, 'eslint')) {
-		return skipped('eslint', 'eslint is not installed')
-	}
+	const reason = project_checks.eslint_skip_reason(directory)
+	if (reason !== undefined) return skipped('eslint', reason)
 
 	return await run_eslint(ESLINT_ARGS, ESLINT_CACHE_FILE)
 }

package/scripts/run/run-step-cli.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
+import { agent_role_profile } from '#scripts/agent/agent-role-profile'
 import { doctor_consumer } from '#scripts/doctor/doctor-consumer'
 import { hook_decision } from '#scripts/josh/hook-decision'
 import { find_package_directory } from '#scripts/josh/josh-logic'
@@ -29,6 +30,7 @@ const RETROSPECTIVE_ENV_KEY = 'JOSH_RETROSPECTIVE'
 interface RunReads {
 	carry_kind: CarryRead['kind']
 	is_retrospective_done: boolean
+	is_at_cut_cap: boolean
 	last_event: string | undefined
 }
 
@@ -36,7 +38,12 @@ interface RunReads {
 // directory that cannot be read leaves the position unknowable, which `next_action` answers `unknown`.
 function read_run(directory: string | undefined, issue_number: string): RunReads {
 	if (directory === undefined) {
-		return { carry_kind: 'unreadable', is_retrospective_done: false, last_event: undefined }
+		return {
+			carry_kind: 'unreadable',
+			is_retrospective_done: false,
+			is_at_cut_cap: false,
+			last_event: undefined,
+		}
 	}
 
 	const carry = run_carry.read_carry(run_carry.carry_path(directory))
@@ -55,6 +62,7 @@ function read_run(directory: string | undefined, issue_number: string): RunReads
 	return {
 		carry_kind: carry.kind,
 		is_retrospective_done: run_carry.retrospective_done_of(carry),
+		is_at_cut_cap: carry.kind === 'carried' && run_carry.is_at_cut_cap(carry.carry),
 		last_event: last?.kind,
 	}
 }
@@ -72,10 +80,12 @@ async function gather(issue_number: string): Promise<StepInput> {
 		last_event: run_reads.last_event,
 		carry_kind: run_reads.carry_kind,
 		is_retrospective_done: run_reads.is_retrospective_done,
+		is_at_cut_cap: run_reads.is_at_cut_cap,
 		is_lane_child: lane_child_marker.is_child_of(process.cwd()),
 		is_consumer: doctor_consumer.is_kit_consumer(find_package_directory(process.cwd())),
 		is_retrospective_enabled: hook_decision.is_switch_opt_in(RETROSPECTIVE_ENV_KEY),
 		has_changes: parts.has_changes,
+		has_completion_callback: agent_role_profile.has_completion_callback(),
 	}
 }
 

package/scripts/run/run-step.ts

@@ -118,6 +118,13 @@ interface StepInput extends PreInput {
 	// are opt-in — so a run that leaves the variable unset never prints the retrospective step, while the
 	// retrospective's own logic is untouched and `pnpm josh retrospective` still runs by hand.
 	is_retrospective_enabled: boolean
+	// Whether this session is woken when a background command it started completes, read by the CLI from
+	// the session's own environment (joshuafolkken/kit#2653). A parent without the callback cannot wait
+	// on its lanes except by polling, so it hands the run to the supervisor instead of waiting.
+	has_completion_callback: boolean
+	// Whether the carried invocation has already taken its maximum cuts, read off the carry record by the
+	// CLI (joshuafolkken/kit#2346). At the cap `run:carry --cut` refuses, so the hand-off is not offered.
+	is_at_cut_cap: boolean
 }
 
 interface StepAction {
@@ -134,10 +141,9 @@ function command(line: string): StepAction {
 }
 
 // The action for each event a run can be positioned at, keyed on the newest one. Each dispatches to the
-// command that owns that phase; `child-launch` is the one position with no command to run — the parent
-// waits for its child. `stop` and `drain` are handled apart in `stop_action` / `drain_action`, because
-// whether either still owes a retrospective needs more than the issue number. A merge and an outage share a next step: `run:merge`
-// classifies both, including the outage's stop condition.
+// command that owns that phase. `stop`, `drain` and `child-launch` are handled apart in
+// `FULL_INPUT_ACTIONS`, because each needs more than the issue number. A merge and an outage share a
+// next step: `run:merge` classifies both, including the outage's stop condition.
 const KIND = run_event_stream.EVENT_KIND
 // A park and a stall share this next step: both mean runnable work is waiting to be offered
 // (joshuafolkken/kit#2359), so both are pointed at the backlog.
@@ -149,7 +155,6 @@ const EVENT_ACTIONS: Record<string, (issue_number: string) => StepAction> = {
 	[KIND.OUTAGE]: (issue_number) => command(`pnpm josh run:merge ${issue_number}`),
 	[KIND.PARK]: () => command(OFFER_BACKLOG),
 	[KIND.CUT]: (issue_number) => command(`pnpm josh run:cut --resume ${issue_number}`),
-	[KIND.CHILD_LAUNCH]: () => verdict(WAIT),
 	// A stall is undispatched ready work with a free lane, so its next step is exactly a park's: offer
 	// the backlog. The detector only reports the stall; reading it here as a dispatch is what turns the
 	// report into the action that resolves it.
@@ -197,12 +202,34 @@ function drain_action(input: StepInput): StepAction {
 	return is_retrospective_owed(input) ? command(RETROSPECTIVE_COMMAND) : verdict(WAIT)
 }
 
-// The two positions whose action needs the whole input rather than the issue number — a stop and a
-// drain both turn on whether the retrospective is still owed. Kept in a map so `next_action` dispatches
-// them in one branch rather than one `if` apiece (`is_retrospective_owed` is the shared gate).
+// The hand-off a `backlogrun` parent without a completion callback takes right after dispatching
+// (joshuafolkken/kit#2653). It is the existing merge-time cut, so the ownership check and the cut cap
+// apply unchanged, and the supervisor's driver adopts the in-flight lanes from their `child-launch`
+// events.
+const HAND_OFF_COMMAND = 'pnpm josh run:carry --cut --owner "$PPID"'
+
+// After a dispatch the parent waits for its child — where waiting is free. A session the completion
+// does not re-invoke could only wait by polling, each poll a model call over its whole context, so a
+// `backlogrun` parent there hands the carry record to the supervisor instead. A lane child and a run
+// with no carry record have nothing to hand off, so both still wait; so does a run at the cut cap, whose
+// cut would be refused on every ask and leave the carry record with nobody.
+function can_hand_off(input: StepInput): boolean {
+	if (input.is_lane_child || input.is_at_cut_cap) return false
+
+	return input.carry_kind === 'carried' && !input.has_completion_callback
+}
+
+function child_launch_action(input: StepInput): StepAction {
+	return can_hand_off(input) ? command(HAND_OFF_COMMAND) : verdict(WAIT)
+}
+
+// The positions whose action needs the whole input rather than the issue number — a stop and a drain
+// both turn on whether the retrospective is still owed, a child launch on whether waiting is free. Kept
+// in a map so `next_action` dispatches them in one branch rather than one `if` apiece.
 const FULL_INPUT_ACTIONS: Record<string, (input: StepInput) => StepAction> = {
 	[KIND.STOP]: stop_action,
 	[KIND.DRAIN]: drain_action,
+	[KIND.CHILD_LAUNCH]: child_launch_action,
 }
 
 // An event the table does not name leaves the position unknown rather than guessing a next step. A
@@ -275,6 +302,7 @@ function next_action(input: StepInput): StepAction {
 const run_step = {
 	ALREADY_DONE,
 	EXPIRED_DECISION,
+	HAND_OFF_COMMAND,
 	HUMAN_REVIEW,
 	IMPLEMENT,
 	KEEP_WORK,

package/templates/pnpm-workspace.static.yaml

@@ -0,0 +1,4 @@
+# Written by `josh init` for a static project (joshuafolkken/kit#2693). kit's CLI runs on tsx, which
+# depends on esbuild, and pnpm fails an install whose dependencies carry an unapproved build script.
+allowBuilds:
+  esbuild: true