@joshuafolkken/kit 1.1379.0 → 1.1387.0

package/scripts/document/document-byte-budget.ts

@@ -74,7 +74,7 @@ const DOCUMENT_BYTE_BUDGET: ReadonlyArray<DocumentBudget> = [
 	{ path: '.claude/skills/workflow-commands/target-repository.md', bytes: 4096 },
 	{ path: '.claude/skills/workflow-commands/working-tree-hold.md', bytes: 8192 },
 	{ path: 'docs/josh-commands-automation.md', bytes: 53_248 },
-	{ path: 'docs/josh-commands-run.md', bytes: 65_536 },
+	{ path: 'docs/josh-commands-run.md', bytes: 69_632 },
 	{ path: 'docs/josh-commands-backlog.md', bytes: 57_344 },
 	{ path: 'docs/josh-commands.md', bytes: 49_152 },
 	{ path: 'docs/labels-and-run-states.md', bytes: 8192 },

package/scripts/epic/epic-candidate-confirm.ts

@@ -111,7 +111,7 @@ function is_still_runnable(
 // A read that failed withholds the candidate rather than confirming it. "Could not tell" is not
 // "nothing blocks it", and this is the one direction the guard may not fail in, because that answer
 // *starts* work — the same reason `epic-busy.ts` answers `wait` for a listing it could not read. The
-// caller then offers the next candidate or waits, and the whole-run timeout bounds the wait.
+// caller then offers the next candidate or waits, and the idle wait bounds the wait.
 async function read_or_withhold(
 	candidate: EpicChild,
 	read_blockers: BlockersReader,

package/scripts/epic/epic-cross-repo.ts

@@ -80,7 +80,7 @@ const NOT_FOUND_STATUS = 404
 //
 // **`absent` is not `unreadable`.** A repository with no
 // manifest, or one whose manifest says `private`, publishes nothing — so a closed blocker there has
-// no release anyone could wait for, and waiting means waiting until the run's own eight-hour timeout
+// no release anyone could wait for, and waiting means waiting until the run's idle wait runs out
 // with nothing an operator can edit to clear it. A read that merely failed says none of that.
 //
 // **It is read from the repository rather than from the registry, and that is the whole design.** The
@@ -123,7 +123,7 @@ type WorkspaceCheck = 'workspace' | 'single' | 'unreadable'
 //
 // **The file's existence proves nothing.** `josh sync` distributes it to every consumer regardless of
 // layout — it carries `allowBuilds`, `overrides` and the like — so probing for its presence would read
-// every private first-party repository as a workspace and wait the eight-hour timeout on each. What
+// every private first-party repository as a workspace and wait the whole idle wait on each. What
 // makes a repository a workspace is a non-empty `packages`
 // key, so that is what is read.
 function declares_packages(yaml: string): boolean {
@@ -271,7 +271,7 @@ function read_default_branch_version(repo: string): string | undefined {
 // would start a dependent before its blocker's release existed. What is asked is only whether the
 // repository *is* a workspace — the members are not enumerated and nothing looks for which of them
 // publishes, so a workspace whose members are all private waits when it need not. That is the safe
-// direction: waiting ends at the run's own timeout, resolving early does not end at all.
+// direction: waiting ends when the run's idle wait runs out, resolving early does not end at all.
 function publishes_nothing(repo: string): boolean {
 	const answer = read_manifest(repo)
 
@@ -285,7 +285,7 @@ function publishes_nothing(repo: string): boolean {
 //
 // **"Ships nothing" is asked first, and it is a different question.** Waiting is right only where
 // something could still arrive; a closed blocker in a repository that publishes no package has no
-// release for `is_published` to ever find, so it would wait until the run's own eight-hour timeout
+// release for `is_published` to ever find, so it would wait until the run's idle wait runs out
 // with nothing an operator could edit to clear it. It is answered from that repository's own manifest and never from
 // the registry, for the reason `ManifestAnswer` records: a registry 404 also means "this token may
 // not see it", and resolving on one would start a consumer child before its blocker's release

package/scripts/epic/epic-next.ts

@@ -194,7 +194,7 @@ function refuse(reason: string): number {
 
 // The verdict as it applies to *this* repository. `run` never reaches a caller here: it means some
 // other repository has work, which for this session is something to wait on rather than a state its
-// loop has a branch for. The whole-run timeout is what bounds that wait.
+// loop has a branch for. The idle wait is what bounds that wait.
 function repo_verdict(verdict: LaneOffer['verdict']): LaneOffer['verdict'] {
 	return verdict === 'run' ? 'wait' : verdict
 }

package/scripts/hooks/stop-guard.ts

@@ -126,20 +126,22 @@ 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.
+// stall needs a backlog driver, which begins one before its plan. An `unreadable`
+// record a crashed run left behind is no run either.
+// The answer is whether that run's owner is still live, and `undefined` where there is no run at all.
 // 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> {
+async function carried_owner_live(): Promise<boolean | undefined> {
 	try {
 		const directory = await run_carry.repository_directory()
 
-		if (directory === undefined) return false
+		if (directory === undefined) return undefined
 
-		return run_carry.read_carry(run_carry.carry_path(directory)).kind === 'carried'
+		const read = run_carry.read_carry(run_carry.carry_path(directory))
+
+		return read.kind === 'carried' ? run_carry.is_owner_live(read.carry) : undefined
 	} catch {
-		return false
+		return undefined
 	}
 }
 
@@ -149,10 +151,19 @@ async function has_run_record(): Promise<boolean> {
 // — 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.
+//
+// **A stall is a live driver not dispatching, so a record whose owner is gone is not asked.** A record
+// stands until a person carries or discards it, so a crashed run's would otherwise re-arm the stall's
+// `git worktree list` and network backlog probe on every stop in the repository, for a run nobody
+// drives. A gone driver is the strand check's question — handed off or not (`run-stranded.ts` →
+// `had_driver`) — and that one reads local files only.
 async function run_report_checks(): Promise<void> {
-	if (!(await has_run_record())) return
+	const is_owner_live = await carried_owner_live()
+
+	if (is_owner_live === undefined) return
+
+	if (is_owner_live) await backlog_stalled_detect.run_stall_check(backlog_ready.DEFAULT_PORTS)
 
-	await backlog_stalled_detect.run_stall_check(backlog_ready.DEFAULT_PORTS)
 	await run_stranded_detect.run_stranded_check()
 }
 

package/scripts/init/start-plan.ts

@@ -9,6 +9,7 @@ interface StartOptions {
 	is_github: boolean
 	visibility: Visibility
 	init_command: string | undefined
+	push_preflight_command: string | undefined
 }
 
 type StartStep = 'git_init' | 'initialize' | 'commit' | 'repository' | 'labels' | 'setup_pr'
@@ -53,7 +54,8 @@ const STEP_LABELS: Readonly<Record<StartStep, string>> = {
 	setup_pr: 'Open an Issue and a pull request that add the kit setup to main',
 }
 
-// The GitHub write steps `--yes` alone never consents to.
+// The GitHub write steps `--yes` alone never consents to. Each one pushes — main, or the setup branch —
+// so they are also the steps a caller's push preflight guards (#3702).
 const GITHUB_WRITE_STEPS: ReadonlySet<StartStep> = new Set(['repository', 'setup_pr'])
 
 function refused(refusal: string): StepPlan {
@@ -107,6 +109,10 @@ function plan_steps(state: GitState): StepPlan {
 	return { steps: FULL_STEPS, refusal: undefined }
 }
 
+function has_push(steps: ReadonlyArray<StartStep>): boolean {
+	return steps.some((step) => GITHUB_WRITE_STEPS.has(step))
+}
+
 function interaction_of(options: StartOptions, is_tty: boolean): Verdict<Interaction> {
 	if (options.is_yes) return { value: 'unattended', refusal: undefined }
 	if (is_tty) return { value: 'interactive', refusal: undefined }
@@ -126,9 +132,7 @@ function github_consent(
 	options: StartOptions,
 	interaction: Interaction,
 ): Verdict<Consent> {
-	const is_github_write = steps.some((step) => GITHUB_WRITE_STEPS.has(step))
-
-	if (!is_github_write || options.is_github) return { value: 'granted', refusal: undefined }
+	if (!has_push(steps) || options.is_github) return { value: 'granted', refusal: undefined }
 	if (interaction === 'interactive') return { value: 'ask', refusal: undefined }
 
 	return {
@@ -158,6 +162,11 @@ function progress_report(
 	return `josh start stopped at: ${labels[failed]}\nCompleted: ${done}\nCause: ${cause}`
 }
 
+// What a run prints when the caller's push preflight fails: no step has run yet, so nothing changed.
+function preflight_report(command: string, cause: string): string {
+	return `josh start stopped before its first step: the push preflight (${command}) failed. Nothing was changed.\nCause: ${cause}`
+}
+
 function plan_summary(
 	steps: ReadonlyArray<StartStep>,
 	labels: Readonly<Record<StartStep, string>> = STEP_LABELS,
@@ -169,9 +178,11 @@ function plan_summary(
 
 const start_plan = {
 	plan_steps,
+	has_push,
 	interaction_of,
 	github_consent,
 	progress_report,
+	preflight_report,
 	plan_summary,
 	step_labels,
 	STEP_LABELS,

package/scripts/init/start-steps.ts

@@ -18,6 +18,7 @@ interface StepContext {
 	profile: ProjectProfile
 	visibility: Visibility
 	init_command: string | undefined
+	push_preflight_command: string | undefined
 }
 
 interface RunContext extends StepContext {
@@ -69,6 +70,13 @@ function self_run_refusal(root: string): string | undefined {
 	return self_sync_guard.self_sync_refusal(PACKAGE_DIR, root)
 }
 
+// A caller's command line runs without a shell, split the way execa splits one.
+function run_command_line(command_line: string, extra: ReadonlyArray<string>, root: string): void {
+	const [command = '', ...args] = parseCommandString(command_line)
+
+	run_local(command, [...args, ...extra], root)
+}
+
 function create_git_repository(context: StepContext): void {
 	initial_commit.create_repository(context.root)
 }
@@ -84,9 +92,7 @@ function initialize(context: StepContext): void {
 		return
 	}
 
-	const [command = '', ...args] = parseCommandString(context.init_command)
-
-	run_local(command, [...args, '--profile', context.profile], context.root)
+	run_command_line(context.init_command, ['--profile', context.profile], context.root)
 }
 
 function commit_all(context: StepContext): void {
@@ -122,6 +128,26 @@ function baseline_of(
 	return start_setup_pr.changed_paths(context.root)
 }
 
+// A toolkit's own pre-push hook can need something kit knows nothing about (app-kit's needs a Docker
+// daemon), and a push it refuses lands after `gh repo create` has made the repository. So the caller
+// names a check that runs only when the plan pushes, before the first step: a run that does not push
+// is never stopped by it, and one it stops has written nothing (#3702).
+function run_push_preflight(steps: ReadonlyArray<StartStep>, context: StepContext): void {
+	const command_line = context.push_preflight_command
+
+	if (command_line === undefined || !start_plan.has_push(steps)) return
+
+	console.info(`\nPush preflight: ${command_line}`)
+
+	try {
+		run_command_line(command_line, [], context.root)
+	} catch (error) {
+		const cause = error_text.message_of(error)
+
+		throw new Error(start_plan.preflight_report(command_line, cause), { cause: error })
+	}
+}
+
 type StepAction = (context: RunContext) => void | Promise<void>
 
 const STEP_ACTIONS: Readonly<Record<StartStep, StepAction>> = {
@@ -150,6 +176,8 @@ async function run_step(
 
 async function run_steps(steps: ReadonlyArray<StartStep>, context: StepContext): Promise<void> {
 	const labels = start_plan.step_labels(context.init_command)
+
+	run_push_preflight(steps, context)
 	const run_context: RunContext = { ...context, baseline: baseline_of(steps, context) }
 
 	for (const [index, step] of steps.entries()) {

package/scripts/init/start.ts

@@ -15,8 +15,9 @@ import { start_steps } from './start-steps'
 const ARGUMENT_START_INDEX = 2
 const READY_MESSAGE = 'GitHub workflow ready. Use kickoff new in your assistant to plan an Issue.'
 const START_USAGE =
-	'josh start [--profile basic|full] [--yes] [--github] [--public] [--init-command <command>]'
+	'josh start [--profile basic|full] [--yes] [--github] [--public] [--init-command <command>] [--push-preflight-command <command>]'
 const INIT_COMMAND_FLAG = '--init-command'
+const PUSH_PREFLIGHT_COMMAND_FLAG = '--push-preflight-command'
 const YES_FLAG = '--yes'
 const GITHUB_FLAG = '--github'
 const PUBLIC_FLAG = '--public'
@@ -28,34 +29,38 @@ interface Prepared {
 	choices: Choices
 }
 
-interface InitCommandSplit {
-	init_command: string | undefined
+interface CommandSplit {
+	command: string | undefined
 	rest: ReadonlyArray<string>
 }
 
 // A value that is blank or another flag means the command itself was left out, which would otherwise
-// swallow the next switch or hand the initialize step nothing to run.
+// swallow the next switch or hand its step nothing to run.
 function is_command_value(value: string | undefined): value is string {
 	return value !== undefined && value.trim() !== '' && !value.startsWith('-')
 }
 
 // The command arrives as the one argument after its flag and is removed together with it.
-function split_init_command(args: ReadonlyArray<string>): InitCommandSplit {
-	const index = args.indexOf(INIT_COMMAND_FLAG)
+function split_command(args: ReadonlyArray<string>, flag: string): CommandSplit {
+	const index = args.indexOf(flag)
 
-	if (index === -1) return { init_command: undefined, rest: args }
+	if (index === -1) return { command: undefined, rest: args }
 
 	const value = args[index + 1]
 
 	if (!is_command_value(value)) throw new Error(`Usage: ${START_USAGE}`)
 
-	return { init_command: value, rest: args.filter((_, at) => at !== index && at !== index + 1) }
+	return { command: value, rest: args.filter((_, at) => at !== index && at !== index + 1) }
 }
 
-// The switches and the initialize command are peeled off first, so what remains is exactly the
+// The switches and the caller's commands are peeled off first, so what remains is exactly the
 // `--profile` pair `josh init` accepts — one parser for the profile in both commands.
 function parse_start_options(args: ReadonlyArray<string>): StartOptions {
-	const { init_command, rest } = split_init_command(args)
+	const init = split_command(args, INIT_COMMAND_FLAG)
+	const { command: push_preflight_command, rest } = split_command(
+		init.rest,
+		PUSH_PREFLIGHT_COMMAND_FLAG,
+	)
 	const profile_args = rest.filter((argument) => !SWITCHES.has(argument))
 
 	return {
@@ -63,7 +68,8 @@ function parse_start_options(args: ReadonlyArray<string>): StartOptions {
 		is_yes: rest.includes(YES_FLAG),
 		is_github: rest.includes(GITHUB_FLAG),
 		visibility: rest.includes(PUBLIC_FLAG) ? 'public' : 'private',
-		init_command,
+		init_command: init.command,
+		push_preflight_command,
 	}
 }
 
@@ -112,12 +118,13 @@ async function main(args: ReadonlyArray<string>, is_tty: boolean): Promise<void>
 	const { steps, interaction, choices } = prepare(args, is_tty, process.cwd())
 
 	const { root, options } = choices
-	const { visibility, init_command } = options
+	const { visibility, init_command, push_preflight_command } = options
 
 	console.info(start_plan.plan_summary(steps, start_plan.step_labels(init_command)))
 	const profile = await resolve_profile(choices, interaction)
+	const context = { root, profile, visibility, init_command, push_preflight_command }
 
-	await start_steps.run_steps(steps, { root, profile, visibility, init_command })
+	await start_steps.run_steps(steps, context)
 	console.info(`\n${READY_MESSAGE}`)
 }
 

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

@@ -214,7 +214,7 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 		// credentials, the same reason `run:wake` carries these flags.
 		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
 		description:
-			'Report whether the run is stranded — budget handed off, owner gone, and no supervisor watching',
+			'Report whether the run is stranded — owner gone, no successor holding the budget, and no supervisor watching',
 		category: 'AI tools',
 		reference: ['', 'automation', ['processes', 'notifications']],
 	},

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

@@ -17,7 +17,7 @@ const PROJECT_COMMANDS: Record<string, CommandEntry> = {
 		description: 'Set a project up for the GitHub Issue workflow, from git init to the setup PR',
 		category: 'Project',
 		reference: [
-			`${PROFILE_ARGUMENTS} [--yes] [--github] [--public] [--init-command <command>]`,
+			`${PROFILE_ARGUMENTS} [--yes] [--github] [--public] [--init-command <command>] [--push-preflight-command <command>]`,
 			'developer',
 			['files', 'git', 'network', 'processes'],
 		],

package/scripts/lane/lane-cli.ts

@@ -62,9 +62,7 @@ async function guard_cut_session(): Promise<string | undefined> {
 
 	const read = run_carry.read_carry(run_carry.carry_path(directory))
 
-	if ((read.kind !== 'carried' && read.kind !== 'expired') || read.carry.is_handed_off !== true) {
-		return undefined
-	}
+	if (read.kind !== 'carried' || read.carry.is_handed_off !== true) return undefined
 
 	return run_carry.count_refused_message(read.carry)
 }