@joshuafolkken/kit 1.1370.0 → 1.1379.0

package/scripts/init/security-policy.ts

@@ -0,0 +1,79 @@
+import path from 'node:path'
+import { repo_origin } from '#scripts/discovery/repo-origin'
+import { git_spawn_sync } from '#scripts/git/git-spawn-sync'
+import { file_reader } from '#scripts/lib/read-file'
+
+// A consumer's `SECURITY.md` is its own policy, not kit's: the advisory and release links have to
+// name the repository the file lands in, and kit's account of its own published package is not a
+// fact about that repository. So the consumer copy is written from a template of its own, with the
+// repository filled in, and kit's root `SECURITY.md` stays kit's.
+const SECURITY_MD = 'SECURITY.md'
+const SECURITY_TEMPLATE = 'templates/SECURITY.md'
+const REPOSITORY_PLACEHOLDER = '{{REPOSITORY}}'
+const KIT_ADVISORY_URL = 'https://github.com/joshuafolkken/kit/security/advisories/new'
+const UNRESOLVED_REASON = '`origin` is not a GitHub repository `owner/repo` can be read from'
+const LINK_DELIMITER = /[\s()<>[\]]+/u
+
+// Read from the local `origin` rather than asked of GitHub: the basic profile decides whether to
+// write the file from the same remote, and a policy file must not depend on `gh` being signed in.
+function repository_at(root: string): string | undefined {
+	const url = git_spawn_sync.origin_url(root)
+	const identity = url === undefined ? undefined : repo_origin.parse_origin_url(url)
+
+	return identity === undefined ? undefined : `${identity.owner}/${identity.repo}`
+}
+
+function apply_repository(content: string, repository: string): string {
+	return content.replaceAll(REPOSITORY_PLACEHOLDER, () => repository)
+}
+
+// Throws rather than writing the placeholder through: both copy paths ask `did_skip_unresolved`
+// first, so reaching here without a repository is a caller that skipped the question.
+function apply_repository_for_destination(destination_path: string, content: string): string {
+	if (path.basename(destination_path) !== SECURITY_MD) return content
+	const repository = repository_at(path.dirname(destination_path))
+
+	if (repository === undefined) {
+		throw new Error(`${SECURITY_MD} needs a GitHub origin to name the repository it reports to`)
+	}
+
+	return apply_repository(content, repository)
+}
+
+// A full project synced before the template existed holds kit's own policy under this name, and the
+// skip leaves that file on disk — still sending its readers to kit's advisory form. The form is
+// matched as a whole link target, not as a substring: a longer address that merely starts with it
+// is another address.
+function does_report_to_kit(root: string): boolean {
+	const existing = file_reader.read_if_readable(path.join(root, SECURITY_MD)) ?? ''
+
+	return new Set(existing.split(LINK_DELIMITER)).has(KIT_ADVISORY_URL)
+}
+
+function unresolved_warning(root: string): string {
+	if (!does_report_to_kit(root)) return `  ⚠ skipped   ${SECURITY_MD} (${UNRESOLVED_REASON})`
+
+	return `  ⚠ stale     ${SECURITY_MD} still reports vulnerabilities to joshuafolkken/kit — replace it with your own policy or delete it (${UNRESOLVED_REASON})`
+}
+
+// Without a GitHub `origin` there is no repository for the advisory link to name, so the file is
+// left unwritten — the next `josh sync` after the remote is added writes it.
+function did_skip_unresolved(filename: string, root: string): boolean {
+	if (filename !== SECURITY_MD || repository_at(root) !== undefined) return false
+
+	console.warn(unresolved_warning(root))
+
+	return true
+}
+
+const security_policy = {
+	SECURITY_MD,
+	SECURITY_TEMPLATE,
+	REPOSITORY_PLACEHOLDER,
+	KIT_ADVISORY_URL,
+	repository_at,
+	apply_repository_for_destination,
+	did_skip_unresolved,
+}
+
+export { security_policy }

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

@@ -80,6 +80,9 @@ const MAINTENANCE_COMMANDS: Record<string, CommandEntry> = {
 		description: 'Update all dependencies to latest',
 		category: 'Maintenance',
 		reference: ['', 'developer', ['files', 'network']],
+		// `JOSH_PLAYWRIGHT_BROWSERS` widens the browsers a Playwright bump installs, and a project
+		// keeps that setting in its `.env`.
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
 	},
 }
 /* eslint-enable @typescript-eslint/naming-convention */

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

@@ -88,7 +88,7 @@ const PROJECT_COMMANDS: Record<string, CommandEntry> = {
 	},
 	adopt: {
 		script: 'scripts/adopt/adopt.ts',
-		description: 'Upgrade every installed @joshuafolkken toolkit here and open the pull request',
+		description: 'Upgrade the @joshuafolkken toolkits and other dependencies here, open the PR',
 		category: 'Project',
 		reference: ['[--dry-run]', 'developer', ['files', 'git', 'network', 'processes']],
 	},

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

@@ -125,7 +125,7 @@ const RUN_COMMANDS: Record<string, CommandEntry> = {
 		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']],
+		reference: ['[<issue>]', 'automation', ['network', 'files']],
 	},
 }
 /* eslint-enable @typescript-eslint/naming-convention */

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

@@ -20,7 +20,8 @@ const VERSIONING_COMMANDS: Record<string, CommandEntry> = {
 	// before chaining here, exactly as it already does for `latest:update`.
 	ranges: {
 		script: 'scripts/version/publishable-range-check.ts',
-		description: 'Check that every published dependency range still resolves for a consumer',
+		description:
+			'Check that every published dependency range still resolves for a consumer and no peer range falls below an installed toolkit',
 		category: 'Versioning',
 		reference: ['', 'developer', ['network']],
 	},

package/scripts/lint/cross-file-recheck.ts

@@ -0,0 +1,155 @@
+import { FAIL_EXIT_CODE, type BufferedProcessResult } from '#scripts/lib/buffered-process'
+import type { ESLint } from 'eslint'
+
+// Some rules read other files, and the lint cache keys a verdict on the linted file's own content.
+// So once the other file is fixed, the untouched one keeps its cached error until its own content
+// changes. `import/no-cycle` did it first (joshuafolkken/kit#3641): a cycle closed by editing one
+// side stayed reported on the other. The type-aware rules do it too (joshuafolkken/kit#3667): a call
+// to a function its module did not export yet stays `no-unsafe-call` after the export is added.
+//
+// A red lint run therefore re-reads its cached report: the files reported for a rule that reads
+// other files are linted once more without the cache, and their fresh results replace the cached
+// ones. A green run never reaches this, so the green path costs what it did.
+//
+// Which rules those are is the rule's own statement, never a list kept here: a type-aware rule
+// declares `requiresTypeChecking`, and the `import` plugin's rules resolve the modules they name.
+// That plugin answers to two names: the base config registers it as `import`, and its own preset —
+// whose rules a hand-authored `.js` file keeps — as `import-x`.
+//
+// Only a stale red is re-read. A stale green — the other file broke, the untouched one still
+// answers clean — is not something a report can point at; the type check is what catches it.
+//
+// That holds for a run narrowed to one change's files as much as for the whole tree: the change can
+// hold both files, and the one a later edit leaves alone keeps its cached report.
+//
+// The cached run is asked again through the Node API rather than read off the first run's report:
+// that report is the stylish text, and taking a file out of it means re-deriving its problem
+// counts. The second asking is answered from the cache the first one just wrote.
+const IMPORT_RULE_PATTERN = /^import(?:-x)?\//u
+const FORMATTER = 'stylish'
+const UNCACHED_SUFFIX = '.uncached'
+
+type RulesMeta = ESLint.LintResultData['rulesMeta']
+
+interface Linters {
+	cached: ESLint
+	fresh: ESLint
+}
+
+interface CrossFileRecheckOptions {
+	cache_file: string
+	// What the run linted — the whole tree, or one change's files — so the cached run is asked the
+	// question it was asked the first time.
+	patterns: ReadonlyArray<string>
+	// What the fixture test varies: the directory linted and the configuration it is linted with.
+	eslint_options?: ESLint.Options
+}
+
+// The exit code is eslint's "finished and reported problems", not any failure: a run that could not
+// finish — a configuration that does not load, a rule that threw — exits 2, and asking it again
+// throws the same error here, ahead of both buffered reports.
+function is_red(result: BufferedProcessResult): boolean {
+	return result.exit_code === FAIL_EXIT_CODE
+}
+
+// `requiresTypeChecking` is typescript-eslint's convention, which other type-aware plugins follow;
+// eslint's own type for a rule's docs does not name it.
+function is_type_aware(documentation: object | undefined): boolean {
+	if (documentation === undefined) return false
+
+	return 'requiresTypeChecking' in documentation && documentation.requiresTypeChecking === true
+}
+
+// A problem with no rule is the parser's, about the file itself.
+function reads_other_files(rule_id: string | null, rules_meta: RulesMeta): boolean {
+	if (rule_id === null) return false
+
+	return IMPORT_RULE_PATTERN.test(rule_id) || is_type_aware(rules_meta[rule_id]?.docs)
+}
+
+function suspects_of(linter: ESLint, cached: Array<ESLint.LintResult>): Array<string> {
+	const rules_meta = linter.getRulesMetaForResults(cached)
+
+	return cached
+		.filter((result) =>
+			result.messages.some((message) => reads_other_files(message.ruleId, rules_meta)),
+		)
+		.map((result) => result.filePath)
+}
+
+function cached_options(options: CrossFileRecheckOptions): ESLint.Options {
+	return {
+		...options.eslint_options,
+		cache: true,
+		cacheStrategy: 'content',
+		cacheLocation: options.cache_file,
+	}
+}
+
+// A linter that runs without a cache deletes the cache file it would have used, and that defaults to
+// the very file the lint run keeps. So the uncached linter is pointed at a sibling path nothing
+// ever writes: the re-reading must not cost the next run its whole cache.
+function fresh_options(options: CrossFileRecheckOptions): ESLint.Options {
+	return {
+		...options.eslint_options,
+		cache: false,
+		cacheLocation: `${options.cache_file}${UNCACHED_SUFFIX}`,
+	}
+}
+
+// `eslint` is loaded here, only past a red report: it is an optional peer a basic-profile
+// consumer may not have, and this module is imported by the entry of every `josh lint`, which has to
+// reach its skip notice there.
+async function create_linters(options: CrossFileRecheckOptions): Promise<Linters> {
+	const eslint = await import('eslint')
+
+	return {
+		cached: new eslint.ESLint(cached_options(options)),
+		fresh: new eslint.ESLint(fresh_options(options)),
+	}
+}
+
+async function lint_fresh(
+	linter: ESLint,
+	suspects: Array<string>,
+): Promise<Map<string, ESLint.LintResult>> {
+	const fresh = await linter.lintFiles(suspects)
+
+	return new Map(fresh.map((result) => [result.filePath, result]))
+}
+
+async function report(
+	linter: ESLint,
+	results: Array<ESLint.LintResult>,
+): Promise<Pick<BufferedProcessResult, 'output' | 'exit_code'>> {
+	const formatter = await linter.loadFormatter(FORMATTER)
+	const is_failed = results.some((result) => result.errorCount > 0)
+
+	return { output: await formatter.format(results), exit_code: is_failed ? FAIL_EXIT_CODE : 0 }
+}
+
+// A red about rules that read nothing else is handed back as the run reported it: its cached
+// verdicts are about the files they are keyed on.
+async function verify(
+	result: BufferedProcessResult,
+	options: CrossFileRecheckOptions,
+): Promise<BufferedProcessResult> {
+	if (!is_red(result)) return result
+	const started_at = performance.now()
+	const linters = await create_linters(options)
+	const cached = await linters.cached.lintFiles([...options.patterns])
+	const suspects = suspects_of(linters.cached, cached)
+	if (suspects.length === 0) return result
+	const fresh = await lint_fresh(linters.fresh, suspects)
+	const verified = await report(
+		linters.fresh,
+		cached.map((entry) => fresh.get(entry.filePath) ?? entry),
+	)
+
+	return { ...verified, elapsed_ms: result.elapsed_ms + performance.now() - started_at }
+}
+
+const cross_file_recheck = { verify }
+
+export type { CrossFileRecheckOptions }
+export { cross_file_recheck }

package/scripts/lint/lint-parallel.ts

@@ -8,7 +8,7 @@ import {
 	FAIL_EXIT_CODE,
 	type BufferedProcessResult,
 } from '#scripts/lib/buffered-process'
-import { cycle_recheck, type CycleRecheckOptions } from './cycle-recheck'
+import { cross_file_recheck, type CrossFileRecheckOptions } from './cross-file-recheck'
 
 const PRETTIER_ARGS = ['exec', 'prettier', '--check', '.'] as const
 // This — not the `lint:eslint` map entry — is the eslint invocation `josh gate` reaches, so the
@@ -17,16 +17,16 @@ const PRETTIER_ARGS = ['exec', 'prettier', '--check', '.'] as const
 // moves, with every test still green.
 const WHOLE_TREE = '.'
 const ESLINT_ARGS = ['exec', 'eslint', WHOLE_TREE, ...ESLINT_CACHE_FLAGS] as const
-const WHOLE_TREE_RECHECK: CycleRecheckOptions = {
+const WHOLE_TREE_RECHECK: CrossFileRecheckOptions = {
 	cache_file: ESLINT_CACHE_FILE,
 	patterns: [WHOLE_TREE],
 }
 
-// What one eslint run is made of: the child's arguments, and what re-reading a cached cycle report
-// (joshuafolkken/kit#3641) needs to ask the same question again — the cache file and the targets.
+// What one eslint run is made of: the child's arguments, and what re-reading a cached cross-file report
+// (`cross-file-recheck.ts`) needs to ask the same question again — the cache file and the targets.
 interface EslintRun {
 	args: ReadonlyArray<string>
-	recheck: CycleRecheckOptions
+	recheck: CrossFileRecheckOptions
 }
 
 // The finished report is re-read before it is returned, inside the lane's cache sharing, because
@@ -35,7 +35,7 @@ async function run_eslint(eslint: EslintRun): Promise<BufferedProcessResult> {
 	return await lane_cache_run.run(eslint.recheck.cache_file, async () => {
 		const result = await buffered_process.run_buffered_process(eslint.args)
 
-		return await cycle_recheck.verify(result, eslint.recheck)
+		return await cross_file_recheck.verify(result, eslint.recheck)
 	})
 }
 
@@ -80,12 +80,13 @@ function lint_exit_code(prettier: BufferedProcessResult, eslint: BufferedProcess
 // run would have skipped. The skip reasons answer nothing for a full
 // project, so the one path serves both profiles.
 //
-// A narrowed run re-reads a cached cycle report too (joshuafolkken/kit#3641): one change's files can
-// hold both sides of a cycle, and closing it by editing one leaves the other's cached report standing.
+// A narrowed run re-reads a cached cross-file report too (`cross-file-recheck.ts`): one change's
+// files can hold both the reported file and the one it reads, and fixing the second leaves the
+// first's cached report standing.
 async function run_lint_checks(
 	prettier_args: ReadonlyArray<string>,
 	eslint_args: ReadonlyArray<string>,
-	recheck: CycleRecheckOptions,
+	recheck: CrossFileRecheckOptions,
 ): Promise<number> {
 	const directory = process.cwd()
 	const [prettier, eslint] = await Promise.all([

package/scripts/lint/lint-related-scope.ts

@@ -9,7 +9,7 @@ import {
 	ESLINT_RELATED_CACHE_FILE,
 	ESLINT_RELATED_CACHE_FLAGS,
 } from '#scripts/josh/josh-command-types'
-import type { CycleRecheckOptions } from './cycle-recheck'
+import type { CrossFileRecheckOptions } from './cross-file-recheck'
 
 // `josh lint` reads the whole repository on every call, and an implementation loop calls it after
 // every few edits — re-reading files the change never touched.
@@ -113,9 +113,9 @@ function eslint_arguments(files: ReadonlyArray<string>): ReadonlyArray<string> {
 	return [...ESLINT_ARGS, ...files, ...ESLINT_RELATED_CACHE_FLAGS, ...ESLINT_SCOPED_FLAGS]
 }
 
-// What re-reading a cached cycle report (`cycle-recheck.ts`) needs to ask the narrowed run's question
+// What re-reading a cached cross-file report (`cross-file-recheck.ts`) needs to ask the narrowed run's question
 // again: the same targets, the same cache file, and the Node API's spelling of `--no-warn-ignored`.
-function cycle_recheck_options(files: ReadonlyArray<string>): CycleRecheckOptions {
+function cross_file_recheck_options(files: ReadonlyArray<string>): CrossFileRecheckOptions {
 	return {
 		cache_file: ESLINT_RELATED_CACHE_FILE,
 		patterns: files,
@@ -125,7 +125,7 @@ function cycle_recheck_options(files: ReadonlyArray<string>): CycleRecheckOption
 
 const lint_related_scope = {
 	COMMAND_LABEL,
-	cycle_recheck_options,
+	cross_file_recheck_options,
 	NOTHING_LINTABLE_REASON,
 	describe_scope,
 	eslint_arguments,

package/scripts/lint/lint-related.ts

@@ -36,7 +36,7 @@ async function lint_exit_code(scope: ChangedFileScope): Promise<number> {
 	return await lint_parallel.run_lint_checks(
 		lint_related_scope.prettier_arguments(scope.files),
 		lint_related_scope.eslint_arguments(scope.files),
-		lint_related_scope.cycle_recheck_options(scope.files),
+		lint_related_scope.cross_file_recheck_options(scope.files),
 	)
 }
 

package/scripts/propagate/propagate-run.ts

@@ -13,6 +13,7 @@ import type { PropagateTarget } from './propagate-targets'
 const STEP_PRECHECK = 'working tree check'
 const STEP_UPGRADE = 'josh vu'
 const STEP_SYNC = 'josh sync'
+const STEP_LATEST = 'josh latest'
 const STEP_LINT_RELATED = 'related lint check'
 const STEP_TEST_RELATED = 'related test check'
 const STEP_VERIFY = 'verification gate'
@@ -32,6 +33,18 @@ const STEP_ORDER: ReadonlyArray<string> = [
 	STEP_PR,
 	STEP_RETURN,
 ]
+// The same sequence with the consumer's other dependencies, its audit and its pnpm pin brought up
+// to date after the sync. Only `josh adopt` runs it: `josh latest` moves every dependency to the
+// registry's newest, which is what adoption is for and exactly what propagation's exact-version wait
+// exists to prevent — and an unrelated dependency's breakage would stop a release reaching a
+// consumer. Derived from `STEP_ORDER` rather than listed, so the two cannot drift apart; behind the
+// sync, because the sync can add devDependencies to `package.json` without installing them, and a
+// pull request opened over that fails CI's frozen install — the step installs before it updates
+// (`propagate_steps`), so the lockfile is re-resolved even when `josh latest` rolls its update back.
+// The related checks and the gate that follow then verify the tree as it will be committed.
+const ADOPT_STEP_ORDER: ReadonlyArray<string> = STEP_ORDER.flatMap((step) =>
+	step === STEP_SYNC ? [step, STEP_LATEST] : step,
+)
 const PROPAGATED_REASON = 'opened a pull request'
 
 type RunOutcome = 'propagated' | 'failed' | 'skipped'
@@ -130,10 +143,11 @@ function run_target(
 	target: PropagateTarget,
 	run_step: RunStep,
 	success_reason: string = PROPAGATED_REASON,
+	order: ReadonlyArray<string> = STEP_ORDER,
 ): TargetResult {
 	const steps: Array<StepResult> = []
 
-	for (const step of STEP_ORDER) {
+	for (const step of order) {
 		const result = run_step(target, step)
 
 		steps.push(result)
@@ -192,11 +206,13 @@ const propagate_run = {
 	STEP_ISSUE,
 	STEP_UPGRADE,
 	STEP_SYNC,
+	STEP_LATEST,
 	STEP_LINT_RELATED,
 	STEP_TEST_RELATED,
 	STEP_VERIFY,
 	STEP_PR,
 	STEP_ORDER,
+	ADOPT_STEP_ORDER,
 	skip_reason,
 	run_target,
 	run_targets,

package/scripts/propagate/propagate-steps.ts

@@ -27,10 +27,17 @@ const SUCCESS_EXIT_CODE = 0
 // pass — so the chain is not repeated here. It resolves in the consumer's directory, which by this
 // point has already been upgraded to the version being propagated, so the command is present.
 const VERIFY_SCRIPT = `pnpm josh ${GATE_COMMAND}`
+// `josh latest` behind an install of its own. The sync can add devDependencies to `package.json`
+// without installing them, and `josh latest` does not always re-resolve the lockfile: when the age
+// gate would downgrade a dependency it restores the files it found and exits zero. Installing first
+// makes the tree it finds a consistent one, so the lockfile matches `package.json` on either path.
+// `--no-frozen-lockfile` because the install exists to write the lockfile, which pnpm refuses under CI.
+const LATEST_SCRIPT = 'pnpm install --no-frozen-lockfile && pnpm josh latest'
 
 // The commands the release-independent spawning steps run inside the target's own directory. The
 // upgrade and the sync are not here: both are per toolkit, so they are built from the plan instead.
 const STEP_COMMANDS: Readonly<Record<string, ReadonlyArray<string>>> = {
+	[propagate_run.STEP_LATEST]: ['sh', '-c', LATEST_SCRIPT],
 	[propagate_run.STEP_LINT_RELATED]: ['pnpm', 'josh', 'lint:related'],
 	[propagate_run.STEP_TEST_RELATED]: ['pnpm', 'josh', 'test:related'],
 	[propagate_run.STEP_VERIFY]: ['sh', '-c', VERIFY_SCRIPT],
@@ -353,7 +360,8 @@ interface Release {
 // `josh propagate` always passes exactly one release; `josh adopt` passes every toolkit installed in
 // the repository it runs in. Only the upgrade and the sync repeat per
 // release — the pre-check, the verification gate, the issue, the pull request and the return to the
-// default branch happen once, which is why the step order itself is unchanged.
+// default branch happen once, which is why the step order does not depend on the plan — `josh adopt`
+// runs `propagate_run.ADOPT_STEP_ORDER`, the same order with `josh latest` added.
 interface ReleasePlan {
 	releases: ReadonlyArray<Release>
 	origin: string

package/scripts/rules/decision-oracle-batch.ts

@@ -106,7 +106,7 @@ const BATCH_ORACLES: ReadonlyArray<DecisionOracle> = [
 	{
 		name: 'run:step',
 		decision: 'The run’s next single action, computed from the event stream, carry and issue state',
-		args: ISSUE_N_ARG,
+		args: `[${ISSUE_N_ARG}]`,
 		// The non-command answers: `run:step` prints a runnable command for a phase with one to run, and
 		// one of these verdicts otherwise. A command line is not a vocabulary token, exactly as an issue
 		// number is not one for `backlog:next`.

package/scripts/run/run-headless.ts

@@ -123,6 +123,7 @@ async function is_backlog_parent(
 const run_headless = {
 	HEADLESS_ENV_KEY,
 	current_carry,
+	driven_here,
 	driving_carry,
 	environment,
 	is_backlog_parent,

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

@@ -13,9 +13,9 @@ import { run_headless } from './run-headless'
 import { run_prep, type PrepParts } from './run-prep'
 import { run_prep_cli } from './run-prep-cli'
 import { run_retrospective } from './run-retrospective'
-import { run_step, type StepInput } from './run-step'
+import { run_step, type ParentInput, type StepInput } from './run-step'
 
-// `josh run:step <N>` — print the run's next single action, computed from the event stream, the carry
+// `josh run:step [<N>]` — print the run's next single action, computed from the event stream, the carry
 // record and the issue state. It reads exactly those three, never the
 // conversation: the issue facts through `run:prep`'s own gather (so this and `run:next` never answer
 // from different reads), the newest event off the stream, and the carry record's kind. The reader runs
@@ -25,7 +25,8 @@ import { run_step, type StepInput } from './run-step'
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const ARGV_OFFSET = 2
-const USAGE = 'Usage: josh run:step <issue-number>'
+const USAGE =
+	'Usage: josh run:step [<issue-number>] — without a number it answers for the `backlogrun` carry record this session drives'
 
 interface RunReads {
 	carry_kind: CarryRead['kind']
@@ -118,7 +119,54 @@ async function gather(issue_number: string): Promise<Gathered> {
 	return { input: step_input(parts, run_reads, is_lane_child), ship_problems: parts.ship_problems }
 }
 
+const UNREADABLE_CARRY: CarryRead = { kind: 'unreadable' }
+
+// The parent's own position — a run asked about with no issue. The last event is the run's newest in
+// scope, whichever issue it names: a parent is positioned by the whole batch, never by one child.
+function parent_reads(directory: string): Pick<ParentInput, 'carry_kind' | 'last_event'> & {
+	carry: CarryRead
+} {
+	const carry = run_carry.read_carry(run_carry.carry_path(directory))
+	const events = run_event_stream.read_events(run_event_stream.target_of(directory))
+	const last = run_event_scope.last_scoped_event(events, run_event_scope.scope_of(carry))
+
+	return { carry, carry_kind: carry.kind, last_event: last?.kind }
+}
+
+function parent_input(directory: string | undefined): ParentInput {
+	const { carry, ...position } =
+		directory === undefined
+			? { carry: UNREADABLE_CARRY, carry_kind: UNREADABLE_CARRY.kind, last_event: undefined }
+			: parent_reads(directory)
+
+	return {
+		...position,
+		is_driving: run_headless.driven_here(carry, lane_reap.own_ancestry) !== undefined,
+		is_handed_off: is_handed_off_here(carry),
+		is_at_cut_cap: carry.kind === 'carried' && run_headless.is_cut_capped(carry.carry),
+		is_lane_child: lane_child_marker.is_child_of(process.cwd()),
+		is_retrospective_done: run_carry.retrospective_done_of(carry),
+		is_consumer: doctor_consumer.is_kit_consumer(find_package_directory(process.cwd())),
+		is_retrospective_enabled: run_retrospective.is_enabled(),
+	}
+}
+
+// `unknown` is the one answer with nothing to run — no record this session drives — so it exits non-zero
+// with the usage, exactly as a position missing its issue state does.
+async function run_parent(): Promise<number> {
+	const { line } = run_step.parent_action(parent_input(await run_carry.repository_directory()))
+
+	console.info(line)
+	if (line !== run_step.UNKNOWN) return SUCCESS_EXIT_CODE
+
+	console.error(USAGE)
+
+	return FAILURE_EXIT_CODE
+}
+
 async function run(argv: ReadonlyArray<string>): Promise<number> {
+	if (argv.length === 0) return await run_parent()
+
 	const issue_number = run_prep_cli.parse_number(argv)
 
 	if (issue_number === undefined) {

package/scripts/run/run-step.ts

@@ -3,7 +3,7 @@ import { session_cite } from '#scripts/issue/session-cite'
 import type { CarryRead } from '#scripts/run/carry/run-carry'
 import { run_event_stream } from '#scripts/run/event/run-event-stream'
 import { latest_scope_cli } from '#scripts/version/latest-scope-cli'
-import { run_retrospective } from './run-retrospective'
+import { run_retrospective, type RetrospectiveFacts } from './run-retrospective'
 
 // `josh run:step <N>` — the run's next single action, computed from three mechanical inputs and nothing
 // else, so the run's loop is not a state machine written in English that the reader rebuilds every
@@ -278,16 +278,19 @@ function closed_action(input: StepInput): StepAction {
 	}
 }
 
+// What the carry record alone says — the part an issue's position and the parent's own share.
+type CarryFacts = Pick<StepInput, 'carry_kind' | 'is_handed_off' | 'is_lane_child'>
+
 // **A cut hands the run on, so the session that took it stops** — otherwise it would go on answering
 // `wait` or the next offer after `run:carry --cut`, launching children in the same conversation. A
 // lane child never holds the carry record, so its own position is not decided here.
-function is_handed_off_parent(input: StepInput): boolean {
+function is_handed_off_parent(input: CarryFacts): boolean {
 	return input.is_handed_off && input.carry_kind === 'carried' && !input.is_lane_child
 }
 
 // The carry record's terminal answers: an unreadable record leaves the position unknowable, a handed-off
 // run is its successor's, and a spent budget is the person's call.
-function carry_terminal_action(input: StepInput): StepAction | undefined {
+function carry_terminal_action(input: CarryFacts): StepAction | undefined {
 	if (input.carry_kind === 'unreadable') return verdict(UNKNOWN)
 	if (is_handed_off_parent(input)) return verdict(STOP)
 	if (input.carry_kind === 'expired') return { kind: 'decide', line: EXPIRED_DECISION }
@@ -308,6 +311,47 @@ function terminal_action(input: StepInput): StepAction | undefined {
 	return undefined
 }
 
+// **A run with no issue still has a next action** — the `backlogrun` parent's own position, read off the
+// carry record alone. Without it a run that dispatched nothing — one begun on an empty backlog — has no
+// position to ask about, and "the backlog is empty, so the run is over" is decided in the conversation
+// instead of by the idle watch.
+interface ParentInput extends RetrospectiveFacts {
+	carry_kind: CarryRead['kind']
+	// Whether this session declared the live record and no cut has handed it off yet.
+	is_driving: boolean
+	is_handed_off: boolean
+	is_at_cut_cap: boolean
+	last_event: string | undefined
+}
+
+// The positions the end-of-run retrospective fires at, whoever asks.
+const RETROSPECTIVE_POSITIONS: ReadonlySet<string> = new Set([KIND.DRAIN, KIND.STOP])
+
+function is_retrospective_position(input: ParentInput): boolean {
+	return RETROSPECTIVE_POSITIONS.has(input.last_event ?? '') && run_retrospective.is_owed(input)
+}
+
+// **The loop belongs to the supervisor, so a driving parent's next action is the hand-off whatever the
+// plan held.** The supervisor starts no driver while a live owner holds the record, and only the driver
+// runs the idle watch. A record at the cut cap has no cut left to take, so its session carries on.
+function driving_action(input: ParentInput): StepAction {
+	if (is_retrospective_position(input)) return command(RETROSPECTIVE_COMMAND)
+
+	return input.is_at_cut_cap ? verdict(WAIT) : command(HAND_OFF_COMMAND)
+}
+
+// A lane child's position is its issue's, and a record this session does not drive — absent, or another
+// session's — is not its to hand off: both are `unknown`, never a guess at someone else's run.
+function parent_action(input: ParentInput): StepAction {
+	if (input.is_lane_child) return verdict(UNKNOWN)
+
+	const terminal = carry_terminal_action(input)
+
+	if (terminal !== undefined) return terminal
+
+	return input.is_driving ? driving_action(input) : verdict(UNKNOWN)
+}
+
 // The one entry point: the run's next action, from the three inputs and nothing else. A terminal answer
 // wins first; otherwise a run with nothing emitted yet is at its pre-implementation position, and a run
 // that has begun is placed by its newest event.
@@ -339,8 +383,9 @@ const run_step = {
 	VOCABULARY,
 	WAIT,
 	next_action,
+	parent_action,
 	pre_verdict,
 }
 
-export type { PreInput, PreVerdict, StepAction, StepInput }
+export type { ParentInput, PreInput, PreVerdict, StepAction, StepInput }
 export { run_step }

package/scripts/sync/sync-ai-files.ts

@@ -5,6 +5,7 @@ import { transform_copied_content } from '#scripts/init/init-copy-content'
 import { init_logic } from '#scripts/init/init-logic'
 import { PACKAGE_DIR, PROJECT_ROOT } from '#scripts/init/init-paths'
 import type { ProjectShape } from '#scripts/init/project-profile'
+import { security_policy } from '#scripts/init/security-policy'
 import { file_reader } from '#scripts/lib/read-file'
 import { pack_hook } from '#scripts/safe-chain/pack-hook'
 import { copy_directory_failure, directory_copy_blocker } from './directory-copy-guard'
@@ -80,6 +81,7 @@ function sync_workspace_yaml(
 
 // The source is the profile's: a basic project syncs from its own templates, as `josh init` wrote it.
 function sync_ai_copy_file(filename: string, is_force: boolean, shape?: ProjectShape): void {
+	if (security_policy.did_skip_unresolved(filename, PROJECT_ROOT)) return
 	const source = init_ai_copy.ai_file_source(filename, shape)
 
 	if (filename === WORKSPACE_YAML) {