@joshuafolkken/kit 1.1094.0 → 1.1136.0

package/scripts/registry-migration/migrate.ts

@@ -115,8 +115,9 @@ async function verify_public_versions(
 
 	for (const [index, [name, version]] of versions.entries()) {
 		const integrity = probed[index]
-		if (integrity === undefined) missing.push(`${name}@${version}`)
-		else integrities.set(version, integrity)
+		const id = `${name}@${version}`
+		if (integrity === undefined) missing.push(id)
+		else integrities.set(id, integrity)
 	}
 
 	return { missing, integrities }
@@ -183,7 +184,7 @@ async function verify_resolution(
 	const old_tarballs = migrate_logic.github_tarballs(lockfile)
 	if (old_tarballs.length > 0) throw new Error(`GitHub tarballs remain: ${old_tarballs.join(', ')}`)
 
-	if (migrate_logic.rewrite_kit_lockfile(lockfile, integrities) !== lockfile) {
+	if (migrate_logic.rewrite_scoped_lockfile(lockfile, integrities) !== lockfile) {
 		throw new Error('lockfile integrity does not match public npm')
 	}
 }
@@ -197,7 +198,7 @@ async function apply(
 		writeFileSync(context.npmrc_path, context.plan.content)
 		writeFileSync(
 			context.lockfile_path,
-			migrate_logic.rewrite_kit_lockfile(context.original_lockfile, integrities),
+			migrate_logic.rewrite_scoped_lockfile(context.original_lockfile, integrities),
 		)
 		await verify_resolution(context, dependencies, integrities)
 	} catch (error) {
@@ -215,7 +216,7 @@ function is_already_migrated(
 ): boolean {
 	return (
 		context.plan.content === context.original_npmrc &&
-		migrate_logic.rewrite_kit_lockfile(context.original_lockfile, integrities) ===
+		migrate_logic.rewrite_scoped_lockfile(context.original_lockfile, integrities) ===
 			context.original_lockfile
 	)
 }

package/scripts/release/github-release-cli.ts

@@ -1,13 +1,24 @@
-import { execFileSync } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
+import { git_spawn_sync } from '#scripts/git/git-spawn-sync'
 import { github_release } from './github-release'
 import { github_release_environment } from './github-release-environment'
 
+// A release published without the tag list would pick its previous tag from nothing, so a failed
+// `git tag` stops the run rather than reading as "no tags".
+function local_tags(): Array<string> {
+	const output = git_spawn_sync.read(['tag', '--list'])
+	if (output === undefined) throw new Error('git tag --list failed')
+
+	return output.split('\n')
+}
+
 async function main(): Promise<void> {
 	const { token, tag, settings } = github_release_environment.read_release_input(process.env)
-	const tags = execFileSync('git', ['tag', '--list'], { encoding: 'utf8' }).trim().split('\n')
 
-	console.info(await github_release.publish(fetch, token, tag, { ...settings, tags }))
+	console.info(await github_release.publish(fetch, token, tag, { ...settings, tags: local_tags() }))
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main()
+
+const github_release_cli = { local_tags }
+export { github_release_cli }

package/scripts/release/github-release-environment.ts

@@ -37,6 +37,7 @@ function read_release_input(environment: Environment): ReleaseInput {
 			start_tag: optional(environment['RELEASE_START_TAG']),
 			workflow: optional(environment['RELEASE_WORKFLOW']),
 			jobs: job_names(environment['RELEASE_JOBS']),
+			await_publish: environment['RELEASE_AWAIT_PUBLISH'] === 'true',
 		},
 	}
 }

package/scripts/release/github-release.ts

@@ -15,7 +15,12 @@ const POLL_INTERVAL_MS = 30_000
 const MAX_WAIT_ATTEMPTS = 120
 const RELEASE_SCHEMA = z.object({ tag_name: z.string().min(1) })
 const NOTES_SCHEMA = z.object({ name: z.string().min(1), body: z.string().min(1) })
-const RUN_SCHEMA = z.object({ id: z.number(), display_title: z.string() })
+const RUN_SCHEMA = z.object({
+	id: z.number(),
+	display_title: z.string(),
+	status: z.string().optional(),
+	conclusion: z.string().nullable().optional(),
+})
 const JOB_SCHEMA = z.object({
 	name: z.string(),
 	status: z.string(),
@@ -26,15 +31,19 @@ const JOBS_SCHEMA = z.object({ jobs: z.array(JOB_SCHEMA) })
 
 type ReleaseRequest = (url: string, init: RequestInit) => Promise<Response>
 type Wait = () => Promise<void>
+type PollState = 'ready' | 'failed' | 'pending'
 
 // What differs between repositories. `start_tag` is the last tag that predates automatic releases;
 // without it the latest existing release is the floor. `workflow` names the publish workflow whose
 // failed run lets a lower tag be skipped, and `jobs` the jobs in it that count (empty: every job).
+// `await_publish` holds the tag's own release until its run in that workflow has succeeded, for a
+// release started beside the publication rather than from inside it.
 interface ReleaseSettings {
 	repository: string
 	start_tag?: string | undefined
 	workflow?: string | undefined
 	jobs?: ReadonlyArray<string> | undefined
+	await_publish?: boolean | undefined
 }
 
 interface PublishOptions extends ReleaseSettings {
@@ -56,7 +65,14 @@ interface Ladder {
 	tags: ReadonlyArray<string>
 	floor: string | undefined
 	fallback?: () => Promise<string>
+	budget: Budget
+}
+
+// One allowance shared by every wait a release makes: waiting for its own publication and then for
+// lower tags' releases must end inside the job's `timeout-minutes` together, not each on its own.
+interface Budget {
 	wait: Wait
+	remaining: number
 }
 
 function request_options(token: string, method: string, body?: object): RequestInit {
@@ -130,13 +146,22 @@ function is_failed_job(job: z.infer<typeof JOB_SCHEMA>, names: ReadonlyArray<str
 	return names.some((name) => job.name === name || job.name.startsWith(`${name} /`))
 }
 
+async function publish_run(
+	client: Client,
+	workflow_name: string,
+	tag: string,
+): Promise<z.infer<typeof RUN_SCHEMA> | undefined> {
+	const workflow = encodeURIComponent(workflow_name)
+	const runs_response = await api_get(client, `/actions/workflows/${workflow}/runs?per_page=100`)
+	const runs = RUNS_SCHEMA.parse(await read_response(runs_response)).workflow_runs
+
+	return runs.find((item) => item.display_title === `Publish ${tag}`)
+}
+
 async function failed_publication(client: Client, tag: string): Promise<boolean> {
 	if (client.workflow === undefined) return false
 
-	const workflow = encodeURIComponent(client.workflow)
-	const runs_response = await api_get(client, `/actions/workflows/${workflow}/runs?per_page=100`)
-	const runs = RUNS_SCHEMA.parse(await read_response(runs_response)).workflow_runs
-	const run = runs.find((item) => item.display_title === `Publish ${tag}`)
+	const run = await publish_run(client, client.workflow, tag)
 	if (!run) return false
 
 	const jobs_response = await api_get(client, `/actions/runs/${String(run.id)}/jobs?per_page=100`)
@@ -149,24 +174,72 @@ async function default_wait(): Promise<void> {
 	await setTimeout(POLL_INTERVAL_MS)
 }
 
-async function release_state(client: Client, tag: string): Promise<'ready' | 'failed' | 'pending'> {
+async function release_state(client: Client, tag: string): Promise<PollState> {
 	if (await existing_release(client, tag)) return 'ready'
 	if (await failed_publication(client, tag)) return 'failed'
 
 	return 'pending'
 }
 
-async function wait_for_release(client: Client, tag: string, wait: Wait): Promise<boolean> {
-	for (let attempt = 0; attempt < MAX_WAIT_ATTEMPTS; attempt += 1) {
+// A run not listed yet is pending too: the announcement that starts this release also starts the
+// publication, so the release can ask before GitHub has queued that run.
+async function publication_state(
+	client: Client,
+	workflow: string,
+	tag: string,
+): Promise<PollState> {
+	const run = await publish_run(client, workflow, tag)
+	if (run?.status !== 'completed') return 'pending'
+
+	return run.conclusion === 'success' ? 'ready' : 'failed'
+}
+
+async function poll(
+	read: () => Promise<PollState>,
+	budget: Budget,
+	subject: string,
+): Promise<boolean> {
+	while (budget.remaining > 0) {
 		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
-		const state = await release_state(client, tag)
+		const state = await read()
 		if (state !== 'pending') return state === 'ready'
 
+		budget.remaining -= 1
 		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
-		await wait()
+		await budget.wait()
 	}
 
-	throw new Error(`Timed out waiting for previous GitHub Release ${tag}`)
+	throw new Error(`Timed out waiting for ${subject}`)
+}
+
+async function wait_for_release(client: Client, tag: string, budget: Budget): Promise<boolean> {
+	return await poll(
+		async () => await release_state(client, tag),
+		budget,
+		`previous GitHub Release ${tag}`,
+	)
+}
+
+async function wait_for_publication(client: Client, tag: string, budget: Budget): Promise<boolean> {
+	const { workflow } = client
+	if (workflow === undefined) throw new Error('Waiting for the publication needs RELEASE_WORKFLOW')
+
+	return await poll(
+		async () => await publication_state(client, workflow, tag),
+		budget,
+		`Publish ${tag}`,
+	)
+}
+
+async function is_publication_ready(
+	client: Client,
+	tag: string,
+	options: PublishOptions,
+	budget: Budget,
+): Promise<boolean> {
+	if (options.await_publish !== true) return true
+
+	return await wait_for_publication(client, tag, budget)
 }
 
 async function ladder_end(ladder: Ladder): Promise<string | undefined> {
@@ -184,7 +257,7 @@ async function baseline_tag(
 	if (ladder.floor === undefined) return prior
 	if (!prior) return await ladder_end(ladder)
 
-	return (await wait_for_release(client, prior, ladder.wait))
+	return (await wait_for_release(client, prior, ladder.budget))
 		? prior
 		: await baseline_tag(client, prior, ladder)
 }
@@ -195,16 +268,19 @@ function assert_older(previous: string | undefined, tag: string): void {
 	}
 }
 
-async function build_ladder(client: Client, options: PublishOptions): Promise<Ladder> {
+async function build_ladder(
+	client: Client,
+	options: PublishOptions,
+	budget: Budget,
+): Promise<Ladder> {
 	const tags = options.tags ?? []
-	const wait = options.wait ?? default_wait
 	const { start_tag } = options
 
 	if (start_tag !== undefined) {
-		return { tags, wait, floor: start_tag, fallback: async () => await previous_tag(client) }
+		return { tags, budget, floor: start_tag, fallback: async () => await previous_tag(client) }
 	}
 
-	return { tags, wait, floor: await latest_release(client) }
+	return { tags, budget, floor: await latest_release(client) }
 }
 
 async function generate_notes(
@@ -252,6 +328,10 @@ function create_client(request: ReleaseRequest, token: string, settings: Release
 	}
 }
 
+function create_budget(options: PublishOptions): Budget {
+	return { wait: options.wait ?? default_wait, remaining: MAX_WAIT_ATTEMPTS }
+}
+
 async function publish(
 	request: ReleaseRequest,
 	token: string,
@@ -263,7 +343,13 @@ async function publish(
 	const client = create_client(request, token, options)
 	if (await existing_release(client, tag)) return 'already-published'
 
-	const previous = await baseline_tag(client, tag, await build_ladder(client, options))
+	const budget = create_budget(options)
+
+	if (!(await is_publication_ready(client, tag, options, budget))) {
+		return `skipped ${tag}: Publish ${tag} did not succeed`
+	}
+
+	const previous = await baseline_tag(client, tag, await build_ladder(client, options, budget))
 
 	assert_older(previous, tag)
 	await create_release(client, tag, previous)

package/scripts/release/release-publish.ts

@@ -2,6 +2,7 @@ import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { git_pr_checks } from '#scripts/gh/git-pr-checks'
 import { git_command } from '#scripts/git/git-command'
 import { git_remote_branch } from '#scripts/git/git-remote-branch'
+import { repository_lock } from '#scripts/git/repository-lock'
 import { write_version } from '#scripts/version/bump-version'
 import { version_targets } from '#scripts/version/version-targets'
 import type { ReleasePlan } from './release-plan'
@@ -20,6 +21,9 @@ const { PACKAGE_JSON } = version_targets
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const IGNORE_FOR_RELEASE_LABEL = 'ignore-for-release'
+const RELEASE_LOCK_PREFIX = 'josh-release-lock-'
+// A release waits on CI for minutes, so a second run refuses rather than queueing behind it.
+const RELEASE_LOCK_MAX_WAIT_MS = 0
 
 function branch_name_for(version: string): string {
 	return `release/v${version}`
@@ -87,6 +91,14 @@ async function refuse_existing_branch(branch_name: string): Promise<void> {
 	throw new Error(existing_branch_message(branch_name))
 }
 
+// **The leftovers go before the guard asks** (joshuafolkken/kit#3058). A run cut off before its
+// `finally`, or a `worktree add` that failed after creating its branch, leaves a local
+// `release/v<version>` that the guard would otherwise refuse as a release already opened.
+async function clear_the_way(branch_name: string): Promise<void> {
+	await release_worktree.clear_leftover()
+	await refuse_existing_branch(branch_name)
+}
+
 // **No `checkout -b` and no branch guard here** (joshuafolkken/kit#2411). The work tree is already
 // sitting on the release branch — `release_worktree.create` cut it that way — and the guard ran
 // before that creation, because `worktree_add` makes the branch local and `branch_exists` would then
@@ -121,10 +133,10 @@ async function merge_and_tag(plan: ReleasePlan, branch_name: string): Promise<nu
 // branch guard runs before the tree exists, `process.chdir` points the version write and the git
 // commands at the tree, and the `finally` returns to the root and removes the tree — whichever way
 // the wait ended, so a failed tag watch cleans up rather than leaving debris behind.
-async function publish(plan: ReleasePlan): Promise<number> {
+async function publish_locked(plan: ReleasePlan): Promise<number> {
 	const branch_name = branch_name_for(plan.next_version)
 
-	await refuse_existing_branch(branch_name)
+	await clear_the_way(branch_name)
 
 	const directory = await release_worktree.create(branch_name)
 	const previous_cwd = process.cwd()
@@ -140,6 +152,28 @@ async function publish(plan: ReleasePlan): Promise<number> {
 	}
 }
 
+function release_running_message(target: string): string {
+	return `Another \`pnpm josh release\` is running in this repository (lock \`${target}\`); wait for it to finish, then run it again.`
+}
+
+// **One release at a time per repository, held for the whole run** (joshuafolkken/kit#3058).
+// `clear_leftover` removes an unpushed, commit-less release branch, which is also what a live run
+// looks like while it installs dependencies — so it may only run once no other release is alive. The
+// lock answers that: a run cut off before its `finally` leaves a record whose owner is gone, which
+// `repository_lock` clears on the next claim, while a live owner makes this run refuse at once.
+async function publish(plan: ReleasePlan): Promise<number> {
+	const target = repository_lock.lock_path(RELEASE_LOCK_PREFIX)
+	const exit_code = await repository_lock.with_lock(
+		async () => await publish_locked(plan),
+		target,
+		RELEASE_LOCK_MAX_WAIT_MS,
+	)
+
+	if (exit_code === undefined) throw new Error(release_running_message(target))
+
+	return exit_code
+}
+
 const release_publish = {
 	branch_name_for,
 	commit_message,

package/scripts/release/release-worktree.ts

@@ -1,7 +1,9 @@
 import path from 'node:path'
 import { git_command } from '#scripts/git/git-command'
+import { git_remote_branch } from '#scripts/git/git-remote-branch'
 import { git_worktree } from '#scripts/git/git-worktree'
 import { lane_install } from '#scripts/lane/lane-install'
+import { lane_leftover } from '#scripts/lane/lane-leftover'
 import { lane_paths } from '#scripts/lane/lane-paths'
 
 // The dedicated linked work tree `pnpm josh release` runs inside (joshuafolkken/kit#2411). The whole
@@ -51,18 +53,111 @@ async function install_or_clean(directory: string, branch_name: string): Promise
 // tree on the default branch, so the tree is created directly on the release branch — `git worktree
 // add --no-track -b release/v<version> <dir> origin/<default>`, which `worktree_add` already spells
 // when it is given a start point.
+//
+// **A failed add takes back the branch it made** (joshuafolkken/kit#3058). `git worktree add -b`
+// creates the branch before it looks at the path, so an add refused for a path that already exists
+// still leaves `release/v<version>` behind — and the next run's branch guard then refuses that name
+// as a release already opened. The guard ran before this call and found no such branch, so one
+// present now is this call's own.
+async function add_or_take_back(directory: string, branch_name: string): Promise<void> {
+	const default_branch = await git_command.get_default_branch()
+
+	try {
+		await git_worktree.worktree_add(directory, branch_name, `origin/${default_branch}`)
+	} catch (error) {
+		if (await git_command.branch_exists(branch_name)) await git_worktree.branch_delete(branch_name)
+
+		throw error
+	}
+}
+
 async function create(branch_name: string): Promise<string> {
 	const directory = directory_for(process.cwd())
-	const default_branch = await git_command.get_default_branch()
 
-	await git_worktree.worktree_add(directory, branch_name, `origin/${default_branch}`)
+	await add_or_take_back(directory, branch_name)
 	await install_or_clean(directory, branch_name)
 
 	return directory
 }
 
+// **A run that never reached its `finally` leaves its tree and branch behind** (joshuafolkken/kit#3058)
+// — a Ctrl-C, a closed terminal — and every later release then fails on them until a person removes
+// both by hand. They are cleared here only when clearing loses nothing: a release branch origin does
+// not have and that carries no commit beyond `origin/<default>`. Uncommitted edits in the tree are
+// the version bump the next run writes again, so they are not counted as a loss. A branch that was
+// pushed, or that holds a commit, may be a release still in flight, so it is reported and kept. A
+// live run with neither yet is excluded by the caller: `release_publish.publish` holds the release
+// lock, so no other release is alive when this runs.
+const RELEASE_BRANCH_PATTERN = 'release/v*'
+
+async function leftover_reason(branch_name: string, base: string): Promise<string | undefined> {
+	const answer = await git_remote_branch.ask(branch_name)
+
+	if (answer !== 'absent') return `origin answers \`${answer}\` for it`
+
+	const ahead = await git_command.commit_count_beyond(base, branch_name)
+
+	return ahead === 0 ? undefined : `it holds ${String(ahead)} commit(s) not on \`${base}\``
+}
+
+function kept_message(directory: string, kept: ReadonlyArray<[string, string]>): string {
+	const lines = kept.map(([branch_name, reason]) => `- \`${branch_name}\`: ${reason}`)
+	const commands = [
+		`git worktree remove --force ${directory}`,
+		...kept.map(([branch_name]) => `git branch -D ${branch_name}`),
+	].join('; ')
+
+	return [
+		'A previous `pnpm josh release` left release branches that may still be in use, so nothing was removed:',
+		...lines,
+		`If no release is running, finish or close its pull request, delete the remote branch if it was pushed, then run \`${commands}\` and \`pnpm josh release\` again.`,
+	].join('\n')
+}
+
+async function kept_branches(branches: ReadonlyArray<string>): Promise<Array<[string, string]>> {
+	const base = `origin/${await git_command.get_default_branch()}`
+	const reasons = await Promise.all(branches.map(async (name) => await leftover_reason(name, base)))
+
+	return branches.flatMap((name, index) => {
+		const reason = reasons[index]
+
+		return reason === undefined ? [] : [[name, reason] as [string, string]]
+	})
+}
+
+async function is_registered(directory: string): Promise<boolean> {
+	const listing = await git_worktree.worktree_list()
+
+	return listing.split('\n').includes(`worktree ${directory}`)
+}
+
+// The tree goes before the branches, for the reason `remove` gives. A directory git does not register
+// is `lane_leftover.reclaim`'s to remove or refuse — the same test a lane's leftover path gets.
+// Registration is asked before existence: a directory deleted by hand stays registered, and git
+// refuses to delete a branch a registered tree holds until `worktree remove` drops the registration.
+async function remove_leftover_tree(directory: string): Promise<void> {
+	if (await is_registered(directory)) await git_worktree.worktree_remove(directory)
+	else await lane_leftover.reclaim(directory)
+}
+
+async function clear_leftover(): Promise<void> {
+	const directory = directory_for(process.cwd())
+	const branches = await git_command.branch_names(RELEASE_BRANCH_PATTERN)
+	const kept = await kept_branches(branches)
+
+	if (kept.length > 0) throw new Error(kept_message(directory, kept))
+
+	await remove_leftover_tree(directory)
+
+	for (const branch_name of branches) {
+		// eslint-disable-next-line no-await-in-loop -- each `branch -D` takes the same ref lock
+		await git_worktree.branch_delete(branch_name)
+	}
+}
+
 const release_worktree = {
 	directory_for,
+	clear_leftover,
 	create,
 	remove,
 	RELEASE_WORKTREE_NAME,

package/scripts/review/review-checkout.ts

@@ -21,8 +21,9 @@ interface ReviewCheckout {
 	head: string
 }
 
-// Three git spawns that do not depend on each other, so they are issued together rather than one
-// after another: the brief is printed in front of a review the run is waiting on.
+// Three git reads that do not depend on each other, so they are issued together rather than one after
+// another: the brief is printed in front of a review the run is waiting on. The root is a near-instant
+// synchronous `rev-parse` (joshuafolkken/kit#3065); the branch and head still overlap.
 async function read_checkout(): Promise<ReviewCheckout> {
 	const [root, branch, head] = await Promise.all([
 		git_command.repository_root(),

package/scripts/review/review-record-cli.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
-import { parseArgs } from 'node:util'
+import { cli_flags } from '#scripts/lib/cli-flags'
 import { observation_ledger_home } from '#scripts/observations/observation-ledger-home'
 import { review_finding_ledger, type Finding } from './review-finding-ledger'
 import { review_record, type RecordVerdict } from './review-record'
@@ -71,21 +71,14 @@ function parse_findings(specs: ReadonlyArray<string>): ReadonlyArray<Finding> |
 }
 
 function parse_argv(argv: ReadonlyArray<string>): Parsed | undefined {
-	try {
-		const parsed = parseArgs({
-			args: [...argv],
-			options: OPTIONS,
-			strict: true,
-			allowPositionals: true,
-		})
-
-		return {
-			check: parsed.values.check === true,
-			issue: parsed.values.issue,
-			positionals: parsed.positionals,
-		}
-	} catch {
-		return undefined
+	const parsed = cli_flags.arguments_of(argv, OPTIONS)
+
+	if (parsed === undefined) return undefined
+
+	return {
+		check: parsed.values.check === true,
+		issue: parsed.values.issue,
+		positionals: parsed.positionals,
 	}
 }
 

package/scripts/rules/early-heartbeat.ts

@@ -185,10 +185,11 @@ function decide(call: GuardedCall, run: GuardRun, can_record: boolean): boolean
 // is the half that makes the rule believable — the promise was kept and the interval was not.
 const EARLY_HEARTBEAT_REASON =
 	'⛔ early heartbeat: this call arms a wait timer of its own, and the progress clock is not yours ' +
-	'to keep. `pnpm josh run:progress --wait` waits the interval out for you ' +
+	'to keep. `pnpm josh run:progress --wait` keeps it for you ' +
 	'(`JOSH_PROGRESS_INTERVAL_MINUTES`, or `josh.progress_interval_minutes` in `package.json`, ' +
-	'default 20 minutes), prints the five labelled lines and exits — start it in the background, relay ' +
-	'the lines it printed when it exits, and start the next one. Two timers armed at ' +
+	'default 20 minutes): start it once in the background and it reports the five labelled lines to ' +
+	"the run's event stream on its own, without waking you — relay nothing, and start it again only " +
+	'after it exits, which it does when newly runnable work arrives. Two timers armed at ' +
 	'once is what produced reports 3–5 minutes apart on a 15-minute setting ' +
 	'(joshuafolkken/kit#1570): a new one was armed on the turn a timer fired and again on the turn a ' +
 	"child's completion woke the run, and `--mark` recorded each report without anything refusing the " +

package/scripts/rules/lane-park.ts

@@ -62,7 +62,15 @@ const NOTIFY_INVOCATION = /josh\s+(?:notify|nf)\b/u
 // notify appears and a `--task-type confirmation` appears. That is looser than `is_confirmation_notify`
 // on purpose — the guard's safe direction is to read a real stop notification as present, so a run
 // that sent one is never told it did not.
+//
+// **A command that sent the Telegram itself prints this line instead** (joshuafolkken/kit#3099):
+// `run:entry` notifies from inside its own stop, so no `josh notify` invocation reaches the transcript,
+// and the line it prints is what the tail carries. One constant, printed there and matched here.
+const COMMAND_NOTIFY_MARKER = 'stop notified: a confirmation Telegram was sent by this command'
+
 function mentions_confirmation_notify(text: string): boolean {
+	if (text.includes(COMMAND_NOTIFY_MARKER)) return true
+
 	return NOTIFY_INVOCATION.test(text) && CONFIRMATION_TASK_TYPE.test(text)
 }
 
@@ -117,6 +125,7 @@ const LANE_PARK_REASON =
 	'before it stops", and the park itself is `backlogrun-park.md` → "park and continue".'
 
 const lane_park = {
+	COMMAND_NOTIFY_MARKER,
 	LANE_PARK_REASON,
 	is_confirmation_notify,
 	is_parking_child,

package/scripts/rules/stop-rules.ts

@@ -162,15 +162,18 @@ const HEADLESS_WAIT_MARKER = '⛔ headless parent:'
 const HEADLESS_REFUSAL_CAP = 3
 
 // The foreground waits as they appear in a transcript's tool-call input — the JSON `command` field, so
-// the refusal's own prose, which names the same commands, never matches.
-const HEADLESS_WAIT_CALLS = ['"command":"pnpm josh lane:await', '"command":"pnpm josh run:progress']
+// the refusal's own prose, which names the same commands, never matches. `run:progress --wait` is not
+// one (joshuafolkken/kit#3102): it streams its reports and runs until work arrives, so it is started in
+// the background, where it lives as long as the turn the foreground wait keeps open.
+const HEADLESS_WAIT_CALLS = ['"command":"pnpm josh lane:await']
 
 const HEADLESS_WAIT_BODY =
 	' this is a `claude -p` `backlogrun` parent (`JOSH_RUN_HEADLESS`) with lanes still ' +
 	'in flight, and ending this turn ends the process — its background waits are killed with it and the ' +
 	'lanes are left without a parent. Wait in the foreground instead: run `pnpm josh lane:await <N...>` ' +
-	'for the in-flight lanes (and `pnpm josh run:progress --wait` for the heartbeat) as foreground ' +
-	'commands within the tool timeout, act on what they report, and continue the loop. End the turn only ' +
+	'for the in-flight lanes as a foreground command within the tool timeout (with ' +
+	'`pnpm josh run:progress --wait` in the background for the heartbeat, which streams its reports ' +
+	'itself and lives while this turn does), act on what it reports, and continue the loop. End the turn only ' +
 	'after `pnpm josh run:carry --cut` or `--end` (`backlogrun-progress.md` → "The parent keeps no clock ' +
 	'of its own").'