@joshuafolkken/kit 1.1050.0 → 1.1094.0

package/scripts/josh/josh-command-map.ts

@@ -40,6 +40,7 @@ const ALIASES: Record<string, string> = {
 	f: 'format',
 	sd: 'cspell:dot',
 	bh: 'behavior',
+	eu: 'exports:unused',
 	t: 'test',
 	tu: 'test:unit',
 	tr: 'test:related',
@@ -62,6 +63,7 @@ const ALIASES: Record<string, string> = {
 	v: 'version',
 	r: 'ranges',
 	dr: 'doctor',
+	rc: 'ruleset:check',
 	pg: 'propagate',
 	ad: 'adopt',
 	ov: 'overrides',

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

@@ -4,10 +4,9 @@ import { DOCUMENT_COMMANDS } from './josh-commands-document'
 import { GUARD_COMMANDS } from './josh-commands-guard'
 import { ISSUE_COMMANDS } from './josh-commands-issue'
 import { LANE_COMMANDS } from './josh-commands-lane'
+import { RUN_COMMANDS } from './josh-commands-run'
 import { SPLIT_COMMANDS } from './josh-commands-split'
 
-// One script answers both `run:hold` and `run:release`; the flag below is what tells them apart.
-const RUN_HOLD_SCRIPT = 'scripts/run/run-hold-cli.ts'
 const ISSUE_WITH_OPTIONS = '<issue> [options]'
 
 /* eslint-disable @typescript-eslint/naming-convention */
@@ -21,7 +20,7 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 		reference: ['<keywords> [--size <n>]', 'automation', ['network']],
 	},
 	'stash:pop': {
-		script: 'scripts/git/stash-pop-cli.ts',
+		script: 'scripts/git/stash/stash-pop-cli.ts',
 		description: 'Pop the stash matching this message, not whichever a shared stack has on top',
 		category: 'AI tools',
 		reference: ['<message>', 'automation', ['git']],
@@ -36,7 +35,7 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 		script: 'scripts/epic/epic-next.ts',
 		description: "List an epic's runnable children, bundled per repository",
 		category: 'AI tools',
-		reference: ['<epic>', 'automation', ['network']],
+		reference: ['<epic>... [--repo <owner/repo>] [--lanes]', 'automation', ['network']],
 	},
 	'epic:bundle': {
 		script: 'scripts/epic/epic-bundle-cli.ts',
@@ -65,9 +64,10 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 	...BACKLOG_COMMANDS,
 	cost: {
 		script: 'scripts/cost-runtime/cost-cli.ts',
-		description: "Report a run's token and credit cost from Claude Code's session transcripts",
+		description:
+			'Say whether the next turn of a run crosses the context-cut threshold (--cut) or a given tokens-per-request figure (--over)',
 		category: 'AI tools',
-		reference: ['[--cut|--over]', 'automation', ['none']],
+		reference: ['(--cut | --over <tokens-per-request>) [--path <dir>]', 'automation', ['none']],
 	},
 	...DOCUMENT_COMMANDS,
 	time: {
@@ -134,100 +134,7 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 		category: 'AI tools',
 		reference: ['<unit-files> <unit-files> [<unit-files> …]', 'automation', ['none']],
 	},
-	'run:hold': {
-		script: RUN_HOLD_SCRIPT,
-		description: 'Claim this working tree for a run, or say which run already holds it',
-		category: 'AI tools',
-		reference: ['[issue]', 'automation', ['files']],
-	},
-	'run:release': {
-		script: RUN_HOLD_SCRIPT,
-		description: "Release this working tree's run record",
-		category: 'AI tools',
-		reference: ['[issue|--force]', 'automation', ['files']],
-		default_script_arguments: ['--release'],
-	},
-	'run:tidy': {
-		script: 'scripts/run/run-tidy-cli.ts',
-		description: 'Close merged lanes and drop stashes whose issues are all merged',
-		category: 'AI tools',
-		reference: ['', 'automation', ['git', 'network', 'files']],
-	},
-	'run:carry': {
-		script: 'scripts/run/run-carry-cli.ts',
-		description: 'Carry one invocation’s budget across its own session cuts',
-		category: 'AI tools',
-		reference: ['<operation> [arguments...]', 'automation', ['files']],
-	},
-	'run:wake': {
-		script: 'scripts/run/run-wake-cli.ts',
-		// `.env` rather than the ambient environment:
-		// the failure warning needs the Telegram credentials, the same
-		// reasons `notify` and `followup` carry these flags.
-		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
-		description: 'Wake the next session of a cut backlogrun from outside the conversation',
-		category: 'AI tools',
-		reference: ['[options]', 'automation', ['processes', 'notifications']],
-	},
-	'run:cut': {
-		script: 'scripts/run/run-cut-cli.ts',
-		description: 'Cut a lane child before the gate and resume a fresh process',
-		category: 'AI tools',
-		reference: ['[--resume] <issue> [--impl] [--handoff <path>]', 'automation', ['files']],
-	},
-	'run:liveness': {
-		script: 'scripts/run/run-liveness-cli.ts',
-		description: 'Say whether a delegated unit is still working, or stopped without reporting',
-		category: 'AI tools',
-		reference: ['<issue> --output <path> [options]', 'automation', ['processes']],
-	},
-	'run:ending': {
-		script: 'scripts/run/run-ending-cli.ts',
-		description: 'Classify how a dispatched lane child ended (merged, cut, abandoned, unreadable)',
-		category: 'AI tools',
-		reference: ['<issue> --output <path> [--repo <owner/repo>]', 'automation', ['network']],
-	},
-	'run:progress': {
-		script: 'scripts/run/run-progress-cli.ts',
-		description: 'Report an unattended run’s progress once it has gone quiet for an interval',
-		category: 'AI tools',
-		reference: ['[--wait|--mark]', 'automation', ['files']],
-	},
-	'run:prep': {
-		script: 'scripts/run/run-prep-cli.ts',
-		description: 'Bundle a run’s pre-edit reads: body, comments, state, dependency scope',
-		category: 'AI tools',
-		reference: ['<issue>', 'automation', ['network']],
-	},
-	// The entry sequence a lane opened on, folded into one call (joshuafolkken/kit#2372): claim the tree,
-	// read the budget, gather the issue reads and decide the pre-implementation step. `run:hold`,
-	// `cost --cut`, `run:prep` and `run:step` were four round trips re-billing a lane's full context each.
-	'run:entry': {
-		script: 'scripts/run/run-entry-cli.ts',
-		description:
-			'Open a run in one call: claim the tree, read the budget, bundle the reads, decide the pre-implementation step',
-		category: 'AI tools',
-		reference: ['<issue>', 'automation', ['git', 'network', 'files']],
-	},
-	'run:status': {
-		script: 'scripts/run/run-status-cli.ts',
-		description: 'Bundle a run’s read-only status: issue state, cost verdict, carry counters',
-		category: 'AI tools',
-		reference: ['<issue> [--repo <owner/repo>]', 'automation', ['network']],
-	},
-	'run:next': {
-		script: 'scripts/run/run-next-cli.ts',
-		description: 'Print the next step a fullrun takes, computed from the run’s state',
-		category: 'AI tools',
-		reference: ['<issue>', 'automation', ['network']],
-	},
-	'run:step': {
-		script: 'scripts/run/run-step-cli.ts',
-		description:
-			'Print the run’s next single action, computed from the event stream, carry record and issue state',
-		category: 'AI tools',
-		reference: ['<issue>', 'automation', ['network', 'files']],
-	},
+	...RUN_COMMANDS,
 	'repo:party': {
 		script: 'scripts/discovery/repo-party-cli.ts',
 		description:
@@ -255,7 +162,7 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 	'run:tail': {
 		script: 'scripts/run/run-tail-cli.ts',
 		description:
-			'Close a run in one call: commit the observation ledger, read the citations, decide the release scope',
+			'Close a run in one call: return to the default branch, commit the observation ledger, read the citations, decide the release scope',
 		category: 'AI tools',
 		reference: ['[<issue> ...]', 'automation', ['git', 'network']],
 	},
@@ -269,7 +176,7 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 			'Ship a change in one call: gate, commit/push/PR, the CI-wait merge and the report bookkeeping, stopping at the first failed step',
 		category: 'AI tools',
 		reference: [
-			'"<title> #<N>" [<follow-up-N> ...] [--cite <N>] [--review] [--detach] [--notify-message <text> | --notify-message-file <path>] | --log <N>',
+			'"<title> #<N>" [<follow-up-N> ...] [--cite <N>] [--review] [--detach] [--body-file <path>] [--notify-message <text> | --notify-message-file <path>] | --log <N>',
 			'automation',
 			['git', 'network'],
 		],

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

@@ -33,7 +33,11 @@ const BACKLOG_COMMANDS: Record<string, CommandEntry> = {
 		description:
 			'Print the whole backlog as a plan: ready now, waiting on what, waiting on a person, out of scope',
 		category: 'AI tools',
-		reference: ['[issue...] [--only]', 'automation', ['network']],
+		reference: [
+			'[issue...] [--only] [--waves] [--exclude <n>[,<n>...]]',
+			'automation',
+			['network'],
+		],
 	},
 	'backlog:stalled': {
 		script: 'scripts/backlog/backlog-stalled-cli.ts',

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

@@ -46,7 +46,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		reference: ['', 'automation', ['processes']],
 	},
 	bytes: {
-		script: 'scripts/bytes/bytes-command.ts',
+		script: 'scripts/lines/bytes-command.ts',
 		description:
 			"Print an agent-read document's byte size against its ceiling and the headroom left",
 		category: 'Development',
@@ -128,6 +128,13 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		category: 'Development',
 		reference: ['', 'developer', ['files']],
 	},
+	'exports:unused': {
+		script: 'scripts/exports/unused-members-cli.ts',
+		description:
+			'Report exported namespace members nothing reads (kit only; a consumer project skips it)',
+		category: 'Development',
+		reference: ['', 'developer', ['none']],
+	},
 	'test:unit': {
 		script: 'scripts/test/test-unit-guard.ts',
 		description:

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

@@ -29,7 +29,7 @@ const ISSUE_COMMANDS: Record<string, CommandEntry> = {
 		description:
 			'Before filing: say whether an issue like this exists and which epic it belongs to',
 		category: 'AI tools',
-		reference: ['<title> [--body <summary>]', 'automation', ['network']],
+		reference: ['<title> [--body <summary> | --body-file <path>]', 'automation', ['network']],
 	},
 	'defect:rate': {
 		script: 'scripts/issue/defect-rate-cli.ts',
@@ -49,7 +49,7 @@ const ISSUE_COMMANDS: Record<string, CommandEntry> = {
 		script: 'scripts/issue/issue-fold-existing-cli.ts',
 		description: 'Assess whether a complete draft can join an unstarted issue',
 		category: 'AI tools',
-		reference: ['<assessment.json>', 'automation', ['none']],
+		reference: ['<assessment.json> [--json]', 'automation', ['none']],
 	},
 	'issue:cite': {
 		script: 'scripts/issue/issue-cite-cli.ts',

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

@@ -10,6 +10,13 @@ const MAINTENANCE_COMMANDS: Record<string, CommandEntry> = {
 		reference: ['[--fix]', 'developer', ['files']],
 		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
 	},
+	'ruleset:check': {
+		script: 'scripts/repo/ruleset-check-cli.ts',
+		description:
+			"Check that the default branch requires every status check kit's workflows report (--apply adds the missing ones)",
+		category: 'Maintenance',
+		reference: ['[--apply]', 'maintainer', ['network']],
+	},
 	overrides: {
 		script: 'scripts/overrides/overrides-check.ts',
 		description: 'Check pnpm overrides for drift',

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

@@ -57,6 +57,12 @@ const PROJECT_COMMANDS: Record<string, CommandEntry> = {
 		category: 'Project',
 		reference: ['<PR>', 'automation', ['network']],
 	},
+	'sonar:new-code': {
+		script: 'scripts/sonar/sonar-new-code-cli.ts',
+		description: 'Fail when a pull request adds any new SonarCloud issue or duplicated block',
+		category: 'Project',
+		reference: ['<PR>', 'automation', ['network']],
+	},
 	'ui:routes': {
 		script: 'scripts/ui/ui-routes-cli.ts',
 		description: 'List the screenshot-target routes the current change touches',

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

@@ -0,0 +1,114 @@
+import { OPTIONAL_ENV_FILE_FLAGS, type CommandEntry } from './josh-command-types'
+
+// The run-lifecycle registry (`run:hold` through `run:step`), split out of `josh-commands-ai.ts` so
+// that file stays under its 300-code-line limit, as `BACKLOG_COMMANDS` and `LANE_COMMANDS` were
+// (joshuafolkken/kit#2992). It is spread into `AI_COMMANDS` at the place the entries used to sit, so
+// the generated catalog keeps their order.
+
+// One script answers both `run:hold` and `run:release`; the flag below is what tells them apart.
+const RUN_HOLD_SCRIPT = 'scripts/run/run-hold-cli.ts'
+
+/* eslint-disable @typescript-eslint/naming-convention */
+const RUN_COMMANDS: Record<string, CommandEntry> = {
+	'run:hold': {
+		script: RUN_HOLD_SCRIPT,
+		description: 'Claim this working tree for a run, or say which run already holds it',
+		category: 'AI tools',
+		reference: ['[<issue> [--fullrun | --halfrun-stop | --prrun-stop]]', 'automation', ['files']],
+	},
+	'run:release': {
+		script: RUN_HOLD_SCRIPT,
+		description: "Release this working tree's run record",
+		category: 'AI tools',
+		reference: ['[issue|--force]', 'automation', ['files']],
+		default_script_arguments: ['--release'],
+	},
+	'run:tidy': {
+		script: 'scripts/run/run-tidy-cli.ts',
+		description: 'Close merged lanes and drop stashes whose issues are all merged',
+		category: 'AI tools',
+		reference: ['', 'automation', ['git', 'network', 'files']],
+	},
+	'run:carry': {
+		script: 'scripts/run/run-carry-cli.ts',
+		description: 'Carry one invocation’s budget across its own session cuts',
+		category: 'AI tools',
+		reference: ['<operation> [arguments...]', 'automation', ['files']],
+	},
+	'run:wake': {
+		script: 'scripts/run/run-wake-cli.ts',
+		// `.env` rather than the ambient environment:
+		// the failure warning needs the Telegram credentials, the same
+		// reasons `notify` and `followup` carry these flags.
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		description: 'Wake the next session of a cut backlogrun from outside the conversation',
+		category: 'AI tools',
+		reference: ['[options]', 'automation', ['processes', 'notifications']],
+	},
+	'run:cut': {
+		script: 'scripts/run/run-cut-cli.ts',
+		description: 'Cut a lane child before the gate and resume a fresh process',
+		category: 'AI tools',
+		reference: ['[--resume] <issue> [--impl] [--handoff <path>]', 'automation', ['files']],
+	},
+	'run:liveness': {
+		script: 'scripts/run/run-liveness-cli.ts',
+		description: 'Say whether a delegated unit is still working, or stopped without reporting',
+		category: 'AI tools',
+		reference: ['<issue> --output <path> [options]', 'automation', ['processes']],
+	},
+	'run:ending': {
+		script: 'scripts/run/run-ending-cli.ts',
+		description: 'Classify how a dispatched lane child ended (merged, cut, abandoned, unreadable)',
+		category: 'AI tools',
+		reference: ['<issue> --output <path> [--repo <owner/repo>]', 'automation', ['network']],
+	},
+	'run:progress': {
+		script: 'scripts/run/run-progress-cli.ts',
+		description: 'Report an unattended run’s progress once it has gone quiet for an interval',
+		category: 'AI tools',
+		reference: [
+			'[--once | --wait] [--interval <minutes>] [--hours <hours>] [--repo <owner/repo>] [--output <path>] | --mark | --path',
+			'automation',
+			['files'],
+		],
+	},
+	'run:prep': {
+		script: 'scripts/run/run-prep-cli.ts',
+		description: 'Bundle a run’s pre-edit reads: body, comments, state, dependency scope',
+		category: 'AI tools',
+		reference: ['<issue>', 'automation', ['network']],
+	},
+	// The entry sequence a lane opened on, folded into one call (joshuafolkken/kit#2372): claim the tree,
+	// read the budget, gather the issue reads and decide the pre-implementation step. `run:hold`,
+	// `cost --cut`, `run:prep` and `run:step` were four round trips re-billing a lane's full context each.
+	'run:entry': {
+		script: 'scripts/run/run-entry-cli.ts',
+		description:
+			'Open a run in one call: claim the tree, read the budget, bundle the reads, decide the pre-implementation step',
+		category: 'AI tools',
+		reference: ['<issue> [--to <command>]', 'automation', ['git', 'network', 'files']],
+	},
+	'run:status': {
+		script: 'scripts/run/run-status-cli.ts',
+		description: 'Bundle a run’s read-only status: issue state, cost verdict, carry counters',
+		category: 'AI tools',
+		reference: ['<issue> [--repo <owner/repo>]', 'automation', ['network']],
+	},
+	'run:next': {
+		script: 'scripts/run/run-next-cli.ts',
+		description: 'Print the next step a fullrun takes, computed from the run’s state',
+		category: 'AI tools',
+		reference: ['<issue>', 'automation', ['network']],
+	},
+	'run:step': {
+		script: 'scripts/run/run-step-cli.ts',
+		description:
+			'Print the run’s next single action, computed from the event stream, carry record and issue state',
+		category: 'AI tools',
+		reference: ['<issue>', 'automation', ['network', 'files']],
+	},
+}
+/* eslint-enable @typescript-eslint/naming-convention */
+
+export { RUN_COMMANDS }

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

@@ -42,6 +42,14 @@ const VERSIONING_COMMANDS: Record<string, CommandEntry> = {
 		category: 'Versioning',
 		reference: ['[--json]', 'automation', ['none']],
 	},
+	// Run by the release workflows, kit's and the one sync distributes, after a tag has published
+	// (joshuafolkken/kit#3007). Settings come from the environment, so the workflow decides them.
+	'release:github': {
+		script: 'scripts/release/github-release-cli.ts',
+		description: 'Create the GitHub Release for a published tag, with generated notes',
+		category: 'Versioning',
+		reference: ['', 'automation', ['network', 'release']],
+	},
 }
 /* eslint-enable @typescript-eslint/naming-convention */
 

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

@@ -35,7 +35,7 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 	// than dropped: `telegram_notify.send` now throws on missing credentials and on a failed send, so
 	// `josh notify` exits non-zero instead of warning and answering 0.
 	followup: {
-		script: 'scripts/git/git-followup-workflow.ts',
+		script: 'scripts/followup/git-followup-workflow.ts',
 		description: 'Follow-up git workflow',
 		category: 'Workflow',
 		reference: [
@@ -46,7 +46,7 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
 	},
 	notify: {
-		script: 'scripts/git/telegram-test.ts',
+		script: 'scripts/notify/telegram-test.ts',
 		description: 'Send Telegram notification',
 		category: 'Workflow',
 		reference: ['--task-type <type> --body <text>', 'automation', ['notifications']],

package/scripts/josh/path-decision.ts

@@ -93,12 +93,9 @@ const path_decision = {
 	format_path_list,
 	has_unknown_flag,
 	JSON_FLAG,
-	KNOWN_FLAGS,
-	MAX_LISTED_PATHS,
 	parse_options,
 	print_decision,
 	run_path_decision,
-	STAGED_FLAG,
 }
 
 export { path_decision }

package/scripts/josh/process-owner.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod'
+
+// The pair a record names its writing process by, as `process_identity` reads it back
+// (joshuafolkken/kit#1245): the pid, and the opaque start token `process_identity.own_fields` wrote
+// beside it. Every lock, marker and ledger entry that later asks `is_same_process` carries this pair,
+// so its shape is declared once here and each record extends it (joshuafolkken/kit#2986).
+//
+// `process_start` is optional because a record written before joshuafolkken/kit#1245, or on a platform
+// whose start time cannot be read, carries only the pid — `is_same_process` has an answer of its own
+// for that case rather than the record being rejected.
+const process_owner_schema = z.object({ pid: z.number(), process_start: z.string().optional() })
+
+type ProcessOwner = z.infer<typeof process_owner_schema>
+
+export { process_owner_schema }
+export type { ProcessOwner }

package/scripts/josh/session-language-cli.ts

@@ -41,7 +41,6 @@ const session_language_cli = {
 	DEFAULT_SESSION_LANG,
 	ENV_KEY,
 	format_line,
-	main,
 	resolve_session_lang,
 	SCOPE_NOTE,
 }

package/scripts/lane/lane-await.ts

@@ -1,8 +1,7 @@
 import { spawnSync } from 'node:child_process'
 import { setTimeout as sleep } from 'node:timers/promises'
-import { git_common_directory } from '#scripts/git/git-common-directory'
-import { run_ship_detach } from '#scripts/run/run-ship-detach'
 import { lane_child_invocation } from './lane-child-invocation'
+import { lane_handoff } from './lane-handoff'
 
 // Detached lane children are not harness-tracked processes, so their completion fires no
 // re-invocation event in the parent's session. Without a blocking wait the parent notices only
@@ -52,11 +51,8 @@ function is_process_running_default(issue: string): boolean {
 	const result = spawnSync('pgrep', ['-f', pattern], { encoding: 'utf8' })
 
 	if (result.status === PROCESS_FOUND) return true
-	const repository = git_common_directory.repository(process.cwd())
 
-	return (
-		repository !== undefined && run_ship_detach.read_result(repository, issue)?.result === 'running'
-	)
+	return lane_handoff.is_ship_running(issue, process.cwd())
 }
 
 function make_initial_state(): AwaitState {
@@ -155,6 +151,7 @@ async function wait_for_any(
 
 		if (completed !== undefined) return completed
 
+		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
 		await sleep(config.poll_ms)
 	}
 }

package/scripts/lane/lane-capacity.ts

@@ -1,4 +1,5 @@
 import type { LaneEnvironment } from './lane-paths'
+import { lane_seed_policy } from './lane-seed'
 
 // How many lanes one repository may run at once, and how many of them are free
 // (joshuafolkken/kit#1491).
@@ -54,14 +55,16 @@ function lane_limit(environment: LaneEnvironment = process.env): LimitChoice {
 // Never negative: a repository holding more `in-progress` issues than the limit allows — the limit
 // was lowered, or a stale label outlived its run — has no free lane, and a negative count read as
 // "how many to offer" would be a slice nobody meant.
+//
+// **A limit above the seat count is capped at the seats** (joshuafolkken/kit#3027). `lane:open` refuses
+// a tenth lane however high `JOSH_LANE_LIMIT` is set, so counting free lanes past the seats offers a
+// launch that is bound to be refused.
 function free_lanes(limit: number, occupied: number): number {
-	return Math.max(NO_LANES, limit - occupied)
+	return Math.max(NO_LANES, Math.min(limit, lane_seed_policy.LAST_LANE_SEAT) - occupied)
 }
 
 const lane_capacity = {
-	DEFAULT_LANE_LIMIT,
 	LANE_LIMIT_KEY,
-	read_limit,
 	lane_limit,
 	free_lanes,
 }

package/scripts/lane/lane-child-invocation.ts

@@ -1,4 +1,10 @@
 import { run_issue_number } from '#scripts/run/run-issue-number'
+import { run_ship_next, type ShipResume } from '#scripts/run/run-ship-next'
+import type { Stage } from '#scripts/run/run-ship-stage'
+
+interface ShipStop extends ShipResume {
+	stage: Stage
+}
 
 const CHILD_INVOCATION = 'fullrun'
 const RESUME_GUIDE = '.claude/skills/workflow-commands/pre-gate-cut.md'
@@ -52,17 +58,24 @@ function outage_resume_invocation(issue: string): string {
 
 // The prompt a lane child is relaunched with when its detached ship supervisor stopped at a failed
 // stage (joshuafolkken/kit#2428) — a red gate, a High/Medium review, a failed push or red CI. The agent
-// ended at the hand-off, so this is how control comes back to one: it reads the stopped report through
-// the command `run:step` names, fixes it and hands the region back. It ends with `child_invocation` for
-// the reason `resume_invocation` does — the parent's poll keeps matching the relaunched process.
-function ship_stop_invocation(issue: string): string {
-	const preamble = `Resuming the lane child for issue #${issue} after its detached ship supervisor stopped at a failed stage — do not re-read the workflow-commands entry documents (SKILL.md, fullrun.md). Run \`pnpm josh run:step ${issue}\` and read the stopped report it names, fix what stopped the ship, then hand the region back per chain-rule.md. Do not re-plan or re-implement what is already on the branch.`
+// ended at the hand-off, so this is how control comes back to one: it reads the stopped report, fixes it
+// and hands the region back. It ends with `child_invocation` for the reason `resume_invocation` does —
+// the parent's poll keeps matching the relaunched process.
+//
+// **A known stage puts the next command in the prompt** (joshuafolkken/kit#2964), so the relaunched
+// session runs it rather than re-deriving it from `chain-rule.md`. An OpenAI lane's supervisor sees only
+// that the ship failed, not where, so without a stage the prompt points at `run:step` as before.
+function ship_stop_invocation(issue: string, stop?: ShipStop): string {
+	const opening = `Resuming the lane child for issue #${issue} after its detached ship supervisor stopped at a failed stage — do not re-read the workflow-commands entry documents (SKILL.md, fullrun.md).`
+	const next =
+		stop === undefined
+			? `Run \`pnpm josh run:step ${issue}\` and read the stopped report it names, fix what stopped the ship, then hand the region back per chain-rule.md.`
+			: run_ship_next.next_step(issue, stop.stage, stop)
 
-	return `${preamble} ${child_invocation(issue)}`
+	return `${opening} ${next} Do not re-plan or re-implement what is already on the branch. ${child_invocation(issue)}`
 }
 
 const lane_child_invocation = {
-	CHILD_INVOCATION,
 	child_invocation,
 	outage_resume_invocation,
 	process_pattern,

package/scripts/lane/lane-cli.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { epic_busy } from '#scripts/epic/epic-busy'
-import { git_gh_command } from '#scripts/git/git-gh-command'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
 import type { OpenIssueData } from '#scripts/git/schemas'
 import { issue_cite, type IssueCiter } from '#scripts/issue/issue-cite'
 import { error_text } from '#scripts/lib/error-message'
@@ -417,9 +417,6 @@ const lane_cli = {
 	ALL_FLAG,
 	NONE_TOKEN,
 	USAGE,
-	main,
-	parse_issue,
-	parse_lane_issue,
 	refusal_message,
 	run,
 }

package/scripts/lane/lane-close.ts

@@ -158,6 +158,7 @@ async function close_each(issues: ReadonlyArray<string>): Promise<SweepOutcome>
 	const sweep: SweepOutcome = { closed: [], failed: [] }
 
 	for (const issue of issues) {
+		// eslint-disable-next-line no-await-in-loop -- worktree writes contend for the same registration directory
 		const bucket = (await try_close(issue)) ? sweep.closed : sweep.failed
 
 		bucket.push(issue)
@@ -186,10 +187,7 @@ async function close_all_lanes(): Promise<SweepOutcome> {
 const lane_close = {
 	close_all_lanes,
 	close_lane,
-	lane_root_directory,
-	lane_targets,
 	prune_lanes,
-	remove_lane,
 	resolve_lane,
 }
 

package/scripts/lane/lane-dispatch.ts

@@ -1,8 +1,8 @@
 import { agent_argv, type AgentArgv, type AgentArgvResult } from '#scripts/agent/agent-argv'
 import { agent_role_profile, type AgentProfile } from '#scripts/agent/agent-role-profile'
-import { git_gh_command } from '#scripts/git/git-gh-command'
-import { IN_PROGRESS_LABEL } from '#scripts/git/issue-labels'
-import { telegram_notify } from '#scripts/git/telegram-notify'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { IN_PROGRESS_LABEL } from '#scripts/issue/issue-labels'
+import { telegram_notify } from '#scripts/notify/telegram-notify'
 import { detached_launch } from '#scripts/run/detached-launch'
 import { run_ending } from '#scripts/run/run-ending'
 import { run_event_stream } from '#scripts/run/run-event-stream'
@@ -444,7 +444,6 @@ async function warn_of_problem(outcome: DispatchOutcome, issue: string): Promise
 }
 
 const lane_dispatch = {
-	CHILD_INVOCATION: lane_child_invocation.CHILD_INVOCATION,
 	child_invocation,
 	default_log_path,
 	describe,

package/scripts/lane/lane-environment.ts

@@ -58,10 +58,6 @@ function is_key_line(line: string, key: string): boolean {
 	return body.slice(key.length).trimStart().startsWith(ASSIGNMENT_SEPARATOR)
 }
 
-function is_seed_line(line: string): boolean {
-	return is_key_line(line, PORT_SEED_KEY)
-}
-
 function is_seat_line(line: string): boolean {
 	return is_key_line(line, LANE_SEAT_KEY)
 }
@@ -235,12 +231,7 @@ function with_lane_output(content: string, output: string, profile?: AgentProfil
 }
 
 const lane_environment = {
-	LANE_OUTPUT_KEY,
-	LANE_PROVIDER_KEY,
-	LANE_ROLE_KEY,
-	is_output_line,
 	is_seat_line,
-	is_seed_line,
 	lane_file_content,
 	read_lane_output,
 	read_lane_profile,