@joshuafolkken/kit 1.1383.0 → 1.1387.0

package/dist/hooks/session-lang.js

@@ -6,17 +6,23 @@ import {
   agent_role_profile,
   detached_launch,
   git_common_directory,
+  issue_cite,
+  run_event_stream,
+  run_event_stream_emit,
   run_headless
-} from "./chunk-2X2ART5G.js";
+} from "./chunk-U32VSRNG.js";
+import {
+  error_text
+} from "./chunk-CDY4NFQG.js";
 import {
   josh_environment_file
-} from "./chunk-Y5R47QHU.js";
+} from "./chunk-J3KSS7II.js";
 import {
   agent_session_environment,
   json_value,
   process_identity,
   run_carry
-} from "./chunk-4MGHBTOM.js";
+} from "./chunk-2YSW3CXH.js";
 import {
   stamp_file
 } from "./chunk-NEC4AT4Z.js";
@@ -298,6 +304,32 @@ var agent_argv = {
   with_resume_in
 };
 
+// scripts/run/event/run-event-setup.ts
+var STAGE = {
+  // `josh backlogrun` started the parent session, which is reading its procedure.
+  STARTING: "starting session",
+  // `run:carry --begin` claimed the run, and the parent is planning it.
+  PLANNING: "planning",
+  // The supervisor took the run over from the parent and is asking for the first offer.
+  HANDING_OFF: "handing off"
+};
+var OPENING = "opening lane";
+function opening_lane(issue) {
+  return `${OPENING} ${issue_cite.plain(issue)}`;
+}
+async function emit(text) {
+  await run_event_stream_emit.emit(run_event_stream.EVENT_KIND.SETUP, text);
+}
+function emit_in(repository, text, at) {
+  try {
+    const target = run_event_stream.target_of(repository);
+    run_event_stream.append(target, run_event_stream.EVENT_KIND.SETUP, text, at.toISOString());
+  } catch (error) {
+    error_text.trace_swallowed("run_event_setup.emit_in", error);
+  }
+}
+var run_event_setup = { STAGE, emit, emit_in, opening_lane };
+
 // scripts/backlog/backlogrun-launch.ts
 import { z } from "zod";
 var LAUNCH_PREFIX = "josh-backlogrun-launch-";
@@ -306,7 +338,11 @@ var LOG_SUFFIX = ".log";
 var launch_schema = z.object({
   pid: z.number(),
   start: z.string().optional(),
-  session: z.string().optional()
+  session: z.string().optional(),
+  // What the parent was started to run and when, so `run:board` has a run to draw and a clock to count
+  // before the parent claims the carry record. Absent on a record an earlier version wrote.
+  invocation: z.string().optional(),
+  started_at: z.string().optional()
 });
 function launch_path(git_directory) {
   return stamp_file.stamp_path(LAUNCH_PREFIX, git_directory);
@@ -348,9 +384,27 @@ function argv_of(invocation, provider, worktree, session) {
 function note_to_stderr(note) {
   console.error(`backlogrun: ${note}`);
 }
-function record_launch(git_directory, pid, session) {
-  const started = process_identity.read_start(pid);
-  stamp_file.replace_stamp(launch_path(git_directory), { pid, start: started, session });
+function record_launch(git_directory, launch) {
+  const now = /* @__PURE__ */ new Date();
+  const identity = process_identity.read_start(launch.pid);
+  const record = { ...launch, start: identity, started_at: now.toISOString() };
+  stamp_file.replace_stamp(launch_path(git_directory), record);
+  run_event_setup.emit_in(git_directory, run_event_setup.STAGE.STARTING, now);
+}
+function live_launch(git_directory) {
+  const record = read_launch(launch_path(git_directory));
+  return is_launch_live(record) ? record : void 0;
+}
+function pending_launch(git_directory) {
+  const { invocation, started_at } = live_launch(git_directory) ?? {};
+  if (invocation === void 0 || started_at === void 0) return void 0;
+  return { invocation, started_at };
+}
+function started_for(git_directory, owner_pid) {
+  const record = live_launch(git_directory);
+  if (record?.started_at === void 0 || record.pid !== owner_pid) return void 0;
+  const started_ms = Date.parse(record.started_at);
+  return Number.isNaN(started_ms) ? void 0 : new Date(started_ms);
 }
 function spawn_parent(argv, provider, target) {
   const environment = {
@@ -376,7 +430,7 @@ function start(invocation, provider, target) {
   if (built.kind === "rejected") return { kind: "failed", note: built.note };
   const result = spawn_parent(built, provider, target);
   if (result.kind === "failed") return result;
-  record_launch(target.git_directory, result.pid, session);
+  record_launch(target.git_directory, { pid: result.pid, session, invocation });
   const launched = { pid: result.pid, session, log_path: log_path(target.git_directory) };
   return { kind: "launched", launched };
 }
@@ -384,7 +438,9 @@ var backlogrun_launch = {
   argv_of,
   chosen_environment,
   is_running,
-  start
+  pending_launch,
+  start,
+  started_for
 };
 
 // scripts/josh/session-language-cli.ts

package/dist/hooks/stop-guard.js

@@ -13,10 +13,8 @@ import {
   lane_park,
   repo_party,
   run_cut,
-  run_event_stream,
-  run_event_stream_emit,
   run_hold
-} from "./chunk-6AC4C2IO.js";
+} from "./chunk-GNDJ7NJ7.js";
 import {
   session_language
 } from "./chunk-6V5OPIUU.js";
@@ -25,23 +23,25 @@ import {
   agent_role_profile,
   issue_cite,
   lane_registry,
+  run_event_stream,
+  run_event_stream_emit,
   run_headless
-} from "./chunk-2X2ART5G.js";
+} from "./chunk-U32VSRNG.js";
 import {
   timed_fetch
 } from "./chunk-FZ6FUSBM.js";
 import "./chunk-CDY4NFQG.js";
 import {
   hook_decision
-} from "./chunk-LC56R53A.js";
+} from "./chunk-EBSHN25W.js";
 import {
   time_density_hook,
   time_hook_transcript,
   time_reported_failure
-} from "./chunk-TT742SIO.js";
+} from "./chunk-SL4GQ2XP.js";
 import {
   lane_child_marker
-} from "./chunk-Y5R47QHU.js";
+} from "./chunk-J3KSS7II.js";
 import {
   backlog_budget,
   issue_number_shape,
@@ -50,7 +50,7 @@ import {
   process_owner_schema,
   run_carry,
   run_invocation
-} from "./chunk-4MGHBTOM.js";
+} from "./chunk-2YSW3CXH.js";
 import {
   PROJECT_ROOT,
   stamp_file
@@ -964,8 +964,53 @@ var run_halfrun_resume = {
   take_over
 };
 
-// scripts/run/wake/run-wake.ts
+// scripts/run/carry/run-carry-ended.ts
+import path from "node:path";
 import { z as z4 } from "zod";
+var ENDED_PREFIX = "josh-run-ended-";
+var TRANSCRIPT_SUFFIX = ".jsonl";
+var ended_run_schema = z4.object({
+  invocation: z4.string(),
+  started_at: z4.string(),
+  ended_at: z4.string(),
+  stopped: z4.string().optional(),
+  session: z4.string().optional()
+});
+function ended_path(git_directory) {
+  return stamp_file.stamp_path(ENDED_PREFIX, git_directory);
+}
+function session_of(transcript) {
+  return transcript === void 0 ? void 0 : path.basename(transcript, TRANSCRIPT_SUFFIX);
+}
+function stop_of(transcript, stopped) {
+  return stopped === void 0 ? {} : { stopped, session: session_of(transcript) };
+}
+function record_ended(target, read, now = /* @__PURE__ */ new Date(), stopped) {
+  if (read.kind !== "carried") return;
+  const { invocation, started_at, owner_transcript } = read.carry;
+  const ended_at = now.toISOString();
+  stamp_file.replace_stamp(target, {
+    invocation,
+    started_at,
+    ended_at,
+    ...stop_of(owner_transcript, stopped)
+  });
+}
+function parse_ended(raw) {
+  return json_value.parse_with(raw, ended_run_schema);
+}
+function read_ended(target) {
+  const raw = stamp_file.read_stamp_text(target);
+  return raw === void 0 ? void 0 : parse_ended(raw);
+}
+function has_ended(target, started_at) {
+  const ended = read_ended(target);
+  return ended !== void 0 && ended.started_at === started_at;
+}
+var run_carry_ended = { ended_path, has_ended, read_ended, record_ended };
+
+// scripts/run/wake/run-wake.ts
+import { z as z5 } from "zod";
 var WAKE_PREFIX = "josh-run-wake-";
 var WAKE_LOG_PREFIX = "josh-run-wake-log-";
 var WAKE_LOG_SUFFIX = ".log";
@@ -984,15 +1029,15 @@ var STOP_REASONS = {
   unreadable: "unreadable"
 };
 var run_wake_schema = process_owner_schema.extend({
-  invocation: z4.string(),
-  started_at: z4.string(),
-  woke: z4.number(),
-  woke_at: z4.string().optional(),
+  invocation: z5.string(),
+  started_at: z5.string(),
+  woke: z5.number(),
+  woke_at: z5.string().optional(),
   // Every optional `RunWake` field must be listed: `z.object` strips undeclared ones on the round trip.
-  attempts: z4.number().optional(),
-  woke_pid: z4.number().optional(),
-  spawned: z4.array(z4.string()).optional(),
-  idle_since: z4.string().optional(),
+  attempts: z5.number().optional(),
+  woke_pid: z5.number().optional(),
+  spawned: z5.array(z5.string()).optional(),
+  idle_since: z5.string().optional(),
   profile: agent_role_profile.PROFILE_SCHEMA.optional()
 });
 function is_overdue(marked_at, now, limit_ms = WAKE_GRACE_MS) {
@@ -1186,10 +1231,12 @@ var run_stranded = {
 
 // scripts/run/run-stranded-detect.ts
 var STRAND_RECOVERY = `Restart supervision with \`${run_stranded.RECOVERY_COMMAND}\` \u2014 it wakes a fresh successor to claim the budget; the cutting session must not resume it itself.`;
+function targets_of(directory) {
+  return { carry: run_carry.carry_path(directory), wake: run_wake.wake_path(directory) };
+}
 async function real_resolve_targets() {
   const directory = await run_carry.repository_directory();
-  if (directory === void 0) return void 0;
-  return { carry: run_carry.carry_path(directory), wake: run_wake.wake_path(directory) };
+  return directory === void 0 ? void 0 : targets_of(directory);
 }
 async function real_emit_stranded(text2) {
   return await run_event_stream_emit.emit_once(run_event_stream.EVENT_KIND.STRANDED, text2);
@@ -1201,14 +1248,13 @@ var DEFAULT_PORTS3 = {
   resolve_targets: real_resolve_targets,
   read_carry: (target) => run_carry.read_carry(target),
   is_owner_live: run_carry.is_owner_live,
+  has_ended: run_carry_ended.has_ended,
   read_wake: (target) => run_wake.read_wake(target),
   supervisor_liveness: (wake) => run_stranded.supervisor_liveness(wake),
   emit_stranded: real_emit_stranded,
   notify_stranded: real_notify_stranded
 };
-async function gather2(ports) {
-  const targets = await ports.resolve_targets();
-  if (targets === void 0) return void 0;
+function input_at(ports, targets) {
   const read = ports.read_carry(targets.carry);
   if (read.kind !== "carried") return void 0;
   return {
@@ -1217,6 +1263,10 @@ async function gather2(ports) {
     supervisor: ports.supervisor_liveness(ports.read_wake(targets.wake))
   };
 }
+async function gather2(ports) {
+  const targets = await ports.resolve_targets();
+  return targets === void 0 ? void 0 : input_at(ports, targets);
+}
 async function report2(ports, input) {
   if (input.read.kind !== "carried") return;
   const text2 = run_stranded.describe(input.read.carry);
@@ -1235,7 +1285,25 @@ async function run_stranded_check() {
   } catch {
   }
 }
-var run_stranded_detect = { detect_and_report: detect_and_report2, run_stranded_check };
+function is_stranded_at(directory, ports = DEFAULT_PORTS3) {
+  const input = input_at(ports, targets_of(directory));
+  return input !== void 0 && run_stranded.is_stranded(input);
+}
+function is_left_stranded(run, ports = DEFAULT_PORTS3) {
+  const read = ports.read_carry(run.carry_target);
+  if (read.kind !== "carried") return !ports.has_ended(run.ended_target, run.started_at);
+  return run_stranded.is_stranded({
+    read,
+    is_owner_live: run_carry.is_held_by_another(read.carry, ports.is_owner_live),
+    supervisor: run_stranded.GONE
+  });
+}
+var run_stranded_detect = {
+  detect_and_report: detect_and_report2,
+  is_left_stranded,
+  is_stranded_at,
+  run_stranded_check
+};
 
 // scripts/hooks/stop-guard.ts
 async function hold_facts() {

package/dist/josh.js

@@ -2501,7 +2501,7 @@ var PROJECT_COMMANDS = {
     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/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.1383.0",
+  "version": "1.1387.0",
   "name": "@joshuafolkken/kit",
   "description": "Development toolkit for AI-assisted projects: formatting, AI assistant rules and a Git/GitHub Issue workflow for any repository, plus lint, type check, tests and hooks for Node projects",
   "keywords": [

package/scripts/backlog/backlog-drive-cli.ts

@@ -79,10 +79,7 @@ async function read_offer(
 	state: DriveState,
 	context: DriveContext,
 ): Promise<OfferRead | undefined> {
-	await backlog_drive_owner.assert_current(context.owner)
-	const carry = await read_record()
-
-	if (carry === undefined) return undefined
+	const carry = await backlog_drive_owner.assert_current(context.owner)
 	const named = await backlog_drive_named_offer.read(carry, state, context)
 	if (named !== undefined) return named
 
@@ -269,6 +266,7 @@ const backlog_drive_cli = {
 	merge_token,
 	offer_argv: backlog_drive_offer_argv.offer_argv,
 	parse: backlog_drive_args.parse,
+	read_offer,
 	resume_line: backlog_drive_args.resume_line,
 	run,
 	to_offer,

package/scripts/backlog/backlog-drive-launch.ts

@@ -1,5 +1,6 @@
 import { git_stash } from '#scripts/git/stash/git-stash'
 import { lane_launch_cli, type LaunchOutcome } from '#scripts/lane/lane-launch-cli'
+import { run_event_setup } from '#scripts/run/event/run-event-setup'
 import { backlog_drive_owner } from './backlog-drive-owner'
 
 // The driver's lane launch. The parent that ran `josh latest` in the primary
@@ -28,6 +29,7 @@ async function latest_stash(): Promise<string | undefined> {
 
 async function launch(issue: string, owner: string): Promise<LaunchOutcome['kind']> {
 	await backlog_drive_owner.assert_current(owner)
+	await run_event_setup.emit(run_event_setup.opening_lane(issue))
 
 	const outcome = await lane_launch_cli.launch_lane({ issue, stash: await latest_stash() })
 

package/scripts/backlog/backlog-drive-owner.ts

@@ -1,4 +1,18 @@
-import { run_carry, type RunCarry } from '#scripts/run/carry/run-carry'
+import { existsSync } from 'node:fs'
+import { poll } from '#scripts/lib/poll'
+import { run_carry, type CarryRead, type RunCarry } from '#scripts/run/carry/run-carry'
+import { run_carry_ended } from '#scripts/run/carry/run-carry-ended'
+import { backlog_budget } from './backlog-budget'
+
+// **A record that does not read is asked again before the driver gives up on it.** The driver is the
+// only thing looking for work during the idle watch, so ending on one failed read throws away whatever
+// is left of the watch. The read is repeated at the offer's own interval, and
+// the count bounds it: a record that stays unreadable still ends the driver, with the reason said.
+const READ_ATTEMPTS = 6
+const ENDED_MESSAGE = 'The carry record is no longer active.'
+
+// The run this driver last read, so a record that is gone can be told from one `run:carry --end` ended.
+const seen: { started_at?: string } = {}
 
 function owns_record(carry: RunCarry, owner: string): boolean {
 	const current = run_carry.owner_of(Number(owner))
@@ -7,16 +21,69 @@ function owns_record(carry: RunCarry, owner: string): boolean {
 	return has_owner && run_carry.is_owner_live(carry) && !carry.is_handed_off
 }
 
-async function assert_current(owner: string): Promise<void> {
+// `--end` records the run it removes, so an ended run answers at once rather than after the re-reads.
+function is_ended(directory: string): boolean {
+	return run_carry_ended.has_ended(run_carry_ended.ended_path(directory), seen.started_at)
+}
+
+// Whether the file is there is said beside the read, because `none` is the answer both to a record
+// that is gone and to one that is present and could not be opened.
+function unread_note(read: CarryRead, directory: string): string {
+	const presence = existsSync(run_carry.carry_path(directory)) ? 'present' : 'absent'
+
+	return `The carry record read \`${read.kind}\` with its file ${presence}`
+}
+
+function is_settled(read: CarryRead, directory: string): boolean {
+	if (read.kind === 'carried' || is_ended(directory)) return true
+
+	console.error(`${unread_note(read, directory)}; reading it again.`)
+
+	return false
+}
+
+async function read_record(directory: string): Promise<CarryRead> {
+	const target = run_carry.carry_path(directory)
+	let read: CarryRead = { kind: 'none' }
+
+	await poll.poll_until(
+		async () => {
+			read = run_carry.read_carry(target)
+
+			return is_settled(read, directory)
+		},
+		{
+			attempts: READ_ATTEMPTS,
+			interval_ms: backlog_budget.OFFER_INTERVAL_MS,
+			sleeper: async (duration_ms) => {
+				await poll.sleep(duration_ms)
+			},
+		},
+	)
+
+	return read
+}
+
+function unread_message(read: CarryRead, directory: string): string {
+	if (is_ended(directory)) return ENDED_MESSAGE
+
+	return `${unread_note(read, directory)}, ${String(READ_ATTEMPTS)} times in a row.`
+}
+
+async function assert_current(owner: string): Promise<RunCarry> {
 	const directory = await run_carry.repository_directory()
 	if (directory === undefined) throw new Error('The carry record cannot be located.')
 
-	const read = run_carry.read_carry(run_carry.carry_path(directory))
-	if (read.kind !== 'carried') throw new Error('The carry record is no longer active.')
+	const read = await read_record(directory)
+	if (read.kind !== 'carried') throw new Error(unread_message(read, directory))
 
 	if (!owns_record(read.carry, owner)) {
 		throw new Error('The driver no longer owns the carry record.')
 	}
+
+	seen.started_at = read.carry.started_at
+
+	return read.carry
 }
 
-export const backlog_drive_owner = { assert_current }
+export const backlog_drive_owner = { READ_ATTEMPTS, assert_current }

package/scripts/backlog/backlogrun-launch.ts

@@ -11,6 +11,7 @@ import { stamp_file } from '#scripts/josh/stamp-file'
 import { json_value } from '#scripts/lib/json-value'
 import { run_carry, type CarryRead } from '#scripts/run/carry/run-carry'
 import { detached_launch, type LaunchResult } from '#scripts/run/detached-launch'
+import { run_event_setup } from '#scripts/run/event/run-event-setup'
 import { run_headless } from '#scripts/run/run-headless'
 import { z } from 'zod'
 
@@ -34,10 +35,20 @@ const launch_schema = z.object({
 	pid: z.number(),
 	start: z.string().optional(),
 	session: z.string().optional(),
+	// What the parent was started to run and when, so `run:board` has a run to draw and a clock to count
+	// before the parent claims the carry record. Absent on a record an earlier version wrote.
+	invocation: z.string().optional(),
+	started_at: z.string().optional(),
 })
 
 type LaunchRecord = z.infer<typeof launch_schema>
 
+// A launched run the parent has not claimed yet, as far as its record says.
+interface PendingLaunch {
+	invocation: string
+	started_at: string
+}
+
 interface LaunchTarget {
 	// The checkout the parent runs in, and its common git directory the records are keyed on.
 	worktree: string
@@ -117,10 +128,48 @@ function note_to_stderr(note: string): void {
 	console.error(`backlogrun: ${note}`)
 }
 
-function record_launch(git_directory: string, pid: number, session: string | undefined): void {
-	const started = process_identity.read_start(pid)
+// **The record and the run's first stage carry one moment**, so the `starting session` event is never
+// dated before the start the board measures from.
+function record_launch(
+	git_directory: string,
+	launch: Pick<LaunchRecord, 'pid' | 'session' | 'invocation'>,
+): void {
+	const now = new Date()
+	const identity = process_identity.read_start(launch.pid)
+	const record: LaunchRecord = { ...launch, start: identity, started_at: now.toISOString() }
+
+	stamp_file.replace_stamp(launch_path(git_directory), record)
+	run_event_setup.emit_in(git_directory, run_event_setup.STAGE.STARTING, now)
+}
+
+// The live launch record here, `undefined` once the parent it names is gone.
+function live_launch(git_directory: string): LaunchRecord | undefined {
+	const record = read_launch(launch_path(git_directory))
+
+	return is_launch_live(record) ? record : undefined
+}
+
+// The launch `run:board` draws while no carry record stands: one whose record says what it runs and
+// since when.
+function pending_launch(git_directory: string): PendingLaunch | undefined {
+	const { invocation, started_at } = live_launch(git_directory) ?? {}
+
+	if (invocation === undefined || started_at === undefined) return undefined
+
+	return { invocation, started_at }
+}
+
+// When the launch that started `owner_pid` began, for `run:carry --begin` to start the run's clock
+// from: **only the parent this launch started inherits it**, so a run typed inside a session — which has
+// no launch record, or another parent's — still starts at its own `--begin`.
+function started_for(git_directory: string, owner_pid: number | undefined): Date | undefined {
+	const record = live_launch(git_directory)
+
+	if (record?.started_at === undefined || record.pid !== owner_pid) return undefined
+
+	const started_ms = Date.parse(record.started_at)
 
-	stamp_file.replace_stamp(launch_path(git_directory), { pid, start: started, session })
+	return Number.isNaN(started_ms) ? undefined : new Date(started_ms)
 }
 
 // The headless mark holds the parent's turn open while its lanes run, as `run:wake`'s does. The launch
@@ -160,7 +209,7 @@ function start(invocation: string, provider: AgentProvider, target: LaunchTarget
 
 	if (result.kind === 'failed') return result
 
-	record_launch(target.git_directory, result.pid, session)
+	record_launch(target.git_directory, { pid: result.pid, session, invocation })
 
 	const launched = { pid: result.pid, session, log_path: log_path(target.git_directory) }
 
@@ -171,8 +220,10 @@ const backlogrun_launch = {
 	argv_of,
 	chosen_environment,
 	is_running,
+	pending_launch,
 	start,
+	started_for,
 }
 
-export type { Launched, LaunchTarget, StartResult }
+export type { Launched, LaunchTarget, PendingLaunch, StartResult }
 export { backlogrun_launch }

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