@joshuafolkken/kit 1.929.0 → 1.953.0

package/scripts/observations/observation-ledger-migrate.ts

@@ -0,0 +1,146 @@
+import { appendFileSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync } from 'node:fs'
+import path from 'node:path'
+import {
+	LEGACY_OBSERVATION_LEDGER_PATH,
+	MIGRATION_CLAIM_SUFFIX,
+	OBSERVATION_LEDGER_PATH,
+} from './observation-ledger'
+import { observation_ledger_line } from './observation-ledger-line'
+
+// Moves the ledger's lines from the path it had before joshuafolkken/kit#2724 to the one it has now
+// (`observation-ledger.ts` carries why both are recognized). Changing the constant alone split the
+// appends across two files: a run still on the old code recreated `docs/observations.md`, and a
+// consumer repository's existing ledger stayed where nothing read it. So resolving the ledger's path
+// migrates first (`observation-ledger-home.ts`), and whatever reached the old path lands at the tail
+// of the new one before anything reads or appends.
+//
+// **The old file is claimed with a rename before it is read.** Two sessions resolving the ledger at
+// once would otherwise both read it and both copy its lines — and a repeated line under one key is
+// what promotes an observation to an issue. A rename succeeds for exactly one of them; the other finds
+// nothing.
+//
+// **A claim whose process is gone is absorbed like the old file itself.** A process killed between the
+// rename and the append leaves the ledger's lines only in the claim file; the next migration finds it
+// by its name and moves it, so no line is stranded where nothing looks.
+//
+// **Synchronous on purpose**: the path resolver every reader and writer calls is synchronous, and a
+// migration with no await point cannot be interleaved with another write in the same process.
+
+const NEWLINE = '\n'
+const NO_SIGNAL = 0
+const NO_SUCH_PROCESS = 'ESRCH'
+
+function claim_path(legacy: string): string {
+	return `${legacy}.${String(process.pid)}${MIGRATION_CLAIM_SUFFIX}`
+}
+
+function claim(from: string, to: string): boolean {
+	try {
+		renameSync(from, to)
+
+		return true
+	} catch {
+		return false
+	}
+}
+
+// Only `ESRCH` means the process is gone; `EPERM` means it runs under another user, and its claim is
+// still its own.
+function is_alive(pid: number): boolean {
+	try {
+		process.kill(pid, NO_SIGNAL)
+
+		return true
+	} catch (error) {
+		return (error as NodeJS.ErrnoException).code !== NO_SUCH_PROCESS
+	}
+}
+
+// A claim is named `<old ledger>.<pid>.migrating`, so the pid is what sits between the two.
+function is_stale_claim(name: string, legacy_name: string): boolean {
+	const prefix = `${legacy_name}.`
+
+	if (!name.startsWith(prefix) || !name.endsWith(MIGRATION_CLAIM_SUFFIX)) return false
+
+	const pid = Number(name.slice(prefix.length, -MIGRATION_CLAIM_SUFFIX.length))
+
+	return Number.isSafeInteger(pid) && !is_alive(pid)
+}
+
+function stale_claims(legacy: string): ReadonlyArray<string> {
+	const directory = path.dirname(legacy)
+
+	try {
+		return readdirSync(directory)
+			.filter((name) => is_stale_claim(name, path.basename(legacy)))
+			.map((name) => path.join(directory, name))
+	} catch {
+		return []
+	}
+}
+
+function terminated(content: string): string {
+	return content.length === 0 || content.endsWith(NEWLINE) ? content : `${content}${NEWLINE}`
+}
+
+function read_or_undefined(file_path: string): string | undefined {
+	try {
+		return readFileSync(file_path, 'utf8')
+	} catch {
+		return undefined
+	}
+}
+
+// What of the claimed file goes to the ledger's tail: all of it, verbatim, when there is no ledger yet,
+// and otherwise only the lines the ledger does not already hold. **The old file can come back after
+// its lines were moved** — `git restore`, `git reset --hard` or a stash without `-u` restores a
+// tracked old ledger beside the untracked new one — and copying it whole again would repeat every line
+// in the history, which the digest reads as every observation recurring.
+function carried(content: string, ledger: string | undefined): string {
+	if (ledger === undefined) return terminated(content)
+
+	const lines = content.split(NEWLINE).filter((line) => line.length > 0)
+	const missing = observation_ledger_line.missing_lines(lines, ledger)
+
+	return missing.length === 0 ? '' : `${missing.join(NEWLINE)}${NEWLINE}`
+}
+
+// Moves one claimed file's lines to the tail of the ledger, then removes the claim.
+function absorb(claimed: string, target: string): void {
+	mkdirSync(path.dirname(target), { recursive: true })
+	appendFileSync(target, carried(readFileSync(claimed, 'utf8'), read_or_undefined(target)), 'utf8')
+	rmSync(claimed)
+}
+
+function absorb_stale(legacy: string, target: string): number {
+	let count = 0
+
+	for (const stale of stale_claims(legacy)) {
+		const claimed = claim_path(legacy)
+
+		if (!claim(stale, claimed)) continue
+
+		absorb(claimed, target)
+		count += 1
+	}
+
+	return count
+}
+
+// Returns whether anything was moved. `root` is the checkout the ledger lives in.
+function migrate(root: string): boolean {
+	const legacy = path.join(root, LEGACY_OBSERVATION_LEDGER_PATH)
+	const target = path.join(root, OBSERVATION_LEDGER_PATH)
+	const recovered = absorb_stale(legacy, target)
+	const claimed = claim_path(legacy)
+
+	if (!claim(legacy, claimed)) return recovered > 0
+
+	absorb(claimed, target)
+
+	return true
+}
+
+const observation_ledger_migrate = { claim_path, migrate }
+
+export { observation_ledger_migrate }

package/scripts/observations/observation-ledger.ts

@@ -4,7 +4,21 @@
 // `observations-flush.ts` is the only thing that stages it — so a literal in each would be three
 // answers to one question, and a rename reaching only some of them would silently restore the
 // contamination the exclusion exists to prevent.
-const OBSERVATION_LEDGER_PATH = 'docs/observations.md'
+//
+// **It sits under `docs/maintainers/`, apart from the reader-facing documents** (joshuafolkken/kit#2724).
+const OBSERVATION_LEDGER_PATH = 'docs/maintainers/observations.md'
+
+// Where the ledger lived before joshuafolkken/kit#2724, kept as a migration source rather than
+// forgotten: a run still on the old code, a stash cut before the move and a consumer repository's
+// existing ledger all write here, and `observation-ledger-migrate.ts` moves what it finds to the path
+// above. Every place that recognizes the ledger recognizes both, so a line on either path is never
+// staged into an ordinary commit. Remove it once every repository holding a ledger has migrated.
+const LEGACY_OBSERVATION_LEDGER_PATH = 'docs/observations.md'
+
+const OBSERVATION_LEDGER_PATHS: ReadonlyArray<string> = [
+	OBSERVATION_LEDGER_PATH,
+	LEGACY_OBSERVATION_LEDGER_PATH,
+]
 
 // `git status --porcelain` prints `XY PATH`, so the path starts at the fourth character.
 const STATUS_PATH_INDEX = 3
@@ -13,8 +27,34 @@ function status_path(line: string): string {
 	return line.slice(STATUS_PATH_INDEX).trim()
 }
 
+// The suffix of the file a migration renames the old ledger to while it copies it
+// (`observation-ledger-migrate.ts`): `docs/observations.md.<pid>.migrating`.
+const MIGRATION_CLAIM_SUFFIX = '.migrating'
+
+// A claim left by a process killed mid-migration holds ledger lines, so it is the ledger too: never
+// staged by an ordinary commit, and absorbed by the next migration.
+function is_migration_claim(file_path: string): boolean {
+	return (
+		file_path.startsWith(`${LEGACY_OBSERVATION_LEDGER_PATH}.`) &&
+		file_path.endsWith(MIGRATION_CLAIM_SUFFIX)
+	)
+}
+
+function is_ledger_path(file_path: string): boolean {
+	return OBSERVATION_LEDGER_PATHS.includes(file_path) || is_migration_claim(file_path)
+}
+
 function is_ledger_line(line: string): boolean {
-	return status_path(line) === OBSERVATION_LEDGER_PATH
+	return is_ledger_path(status_path(line))
+}
+
+// The ledger paths a porcelain status names — what a flush stages after a migration, which may be the
+// new file together with the old one's deletion.
+function ledger_paths(status_output: string): ReadonlyArray<string> {
+	return status_output
+		.split('\n')
+		.filter((line) => is_ledger_line(line))
+		.map((line) => status_path(line))
 }
 
 // **The one place that answers "does this working tree hold a pending observation append?"**
@@ -29,7 +69,15 @@ function has_pending_append(status_output: string): boolean {
 const observation_ledger = {
 	has_pending_append,
 	is_ledger_line,
+	is_ledger_path,
+	ledger_paths,
 	status_path,
 }
 
-export { OBSERVATION_LEDGER_PATH, observation_ledger }
+export {
+	LEGACY_OBSERVATION_LEDGER_PATH,
+	MIGRATION_CLAIM_SUFFIX,
+	OBSERVATION_LEDGER_PATH,
+	OBSERVATION_LEDGER_PATHS,
+	observation_ledger,
+}

package/scripts/observations/observations-flush.ts

@@ -4,6 +4,7 @@ import { git_gh_command } from '#scripts/git/git-gh-command'
 import { main_sync } from '#scripts/git/main-sync'
 import { observation_ledger, OBSERVATION_LEDGER_PATH } from './observation-ledger'
 import { observation_ledger_line, type BrokenLine } from './observation-ledger-line'
+import { observation_ledger_migrate } from './observation-ledger-migrate'
 import { observations_flush_landing } from './observations-flush-landing'
 
 // The commit path the observation ledger did not have (joshuafolkken/kit#1756). The parent session
@@ -78,7 +79,9 @@ function has_ledger_change(status_output: string): boolean {
 }
 
 function other_changed_paths(status_output: string): ReadonlyArray<string> {
-	return status_paths(status_output).filter((file_path) => file_path !== OBSERVATION_LEDGER_PATH)
+	return status_paths(status_output).filter(
+		(file_path) => !observation_ledger.is_ledger_path(file_path),
+	)
 }
 
 function message_of(error: unknown): string {
@@ -295,9 +298,21 @@ function rejection_message(
 	return roll_back_failure_message(branch_name, reason, roll_back_reason)
 }
 
+// **Every ledger path the status names is staged, not the one constant** (joshuafolkken/kit#2724).
+// After a migration the change is the new file together with the old one's deletion, and a commit
+// holding only the first would leave the deletion behind as a change no later flush could tell apart
+// from a fresh append.
+async function stage_ledger(): Promise<void> {
+	const ledger_paths = observation_ledger.ledger_paths(await git_command.status())
+
+	for (const file_path of ledger_paths) {
+		await git_command.add_path(file_path)
+	}
+}
+
 async function commit_ledger(branch_name: string, default_branch: string): Promise<void> {
 	try {
-		await git_command.add_path(OBSERVATION_LEDGER_PATH)
+		await stage_ledger()
 		await git_command.commit(COMMIT_MESSAGE)
 	} catch (error) {
 		const roll_back_reason = await roll_back(branch_name, default_branch)
@@ -316,7 +331,7 @@ async function open_pull_request(branch_name: string, default_branch: string): P
 }
 
 // **The checkout goes back to the default branch only on the way that merged.** A `finally` here
-// would check the default branch out after a red check too — and `docs/observations.md` would then
+// would check the default branch out after a red check too — and the ledger would then
 // revert to main's content, leaving the appended lines on a branch nothing in this checkout points
 // at any more. The next flush would read `has_ledger_change` as false and report `clean`, which is
 // the silent loss the refusals above exist to prevent. Left on the branch, the refusal fires.
@@ -359,14 +374,30 @@ function broken_lines_message(broken: ReadonlyArray<BrokenLine>): string {
 // **A malformed line is refused before a branch is cut, not after.** The ledger path was collected
 // without a line ever being parsed (joshuafolkken/kit#2123), so a broken append could ride a flush
 // through; validating here keeps the committed ledger to its grammar.
+//
+// **A ledger that is not there has no line to break** — the change the status saw is then its
+// deletion, and a flush commits that like any other change to it.
+async function read_ledger(): Promise<string> {
+	try {
+		return await readFile(OBSERVATION_LEDGER_PATH, 'utf8')
+	} catch {
+		return ''
+	}
+}
+
 async function refuse_broken_ledger(): Promise<void> {
-	const broken = observation_ledger_line.broken_ledger_lines(
-		await readFile(OBSERVATION_LEDGER_PATH, 'utf8'),
-	)
+	const broken = observation_ledger_line.broken_ledger_lines(await read_ledger())
 
 	if (broken.length > 0) throw new Error(broken_lines_message(broken))
 }
 
+// Lines still on the ledger's old path are moved before anything is validated or staged
+// (joshuafolkken/kit#2724), so the flush commits the move and the lines together.
+async function prepare_ledger(): Promise<void> {
+	observation_ledger_migrate.migrate(process.cwd())
+	await refuse_broken_ledger()
+}
+
 // **Nothing pulls in front of the branch, and that is deliberate.** The ledger is dirty by
 // definition at this point, so `git pull --ff-only` aborts on it in exactly the case a pull would
 // have been for — an upstream flush that already advanced the ledger — and reports a failure about
@@ -382,7 +413,7 @@ async function flush(now: Date): Promise<string> {
 
 	if (!has_ledger_change(status_output)) return CLEAN_MESSAGE
 
-	await refuse_broken_ledger()
+	await prepare_ledger()
 
 	const deferred = await observations_flush_landing.refuse_open_flush(BRANCH_PREFIX)
 	if (deferred !== undefined) return deferred

package/scripts/review/review-finding-ledger.ts

@@ -1,7 +1,7 @@
 // The review-finding line's grammar, its category vocabulary and the aggregation over it — the single
 // place all three are defined (joshuafolkken/kit#2325). A `/code-review` round's findings evaporated
 // the moment they were fixed, so no one could say which category recurred. They now land in the same
-// append-only ledger the observation lines use (`docs/observations.md`), under a distinct `- rf:`
+// append-only ledger the observation lines use (`docs/maintainers/observations.md`), under a distinct `- rf:`
 // prefix so `observation-ledger-line.ts`'s `- k:` grammar never treats them as its own — one ledger
 // file, one flush path, a second line *type* rather than a second ledger.
 

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

@@ -1,6 +1,4 @@
 #!/usr/bin/env tsx
-import { appendFile, mkdir } from 'node:fs/promises'
-import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { parseArgs } from 'node:util'
 import { observation_ledger_home } from '#scripts/observations/observation-ledger-home'
@@ -154,11 +152,7 @@ async function run_record(parsed: Parsed, now: Date, ledger_path: string): Promi
 
 	const lines = build_lines(request, today(now))
 
-	// A consumer that does not keep the observation ledger has no `docs/` at its root, so the append
-	// below would fail with ENOENT and leave the merge gate unsatisfiable (joshuafolkken/kit#2402).
-	// Creating the parent first is the one write path that can bring the ledger into existence there.
-	await mkdir(path.dirname(ledger_path), { recursive: true })
-	await appendFile(ledger_path, `${lines.join('\n')}\n`, 'utf8')
+	await observation_ledger_home.append(ledger_path, lines)
 	console.info(confirmation(lines.length, ledger_path))
 
 	return 0

package/scripts/rules/delivered-rules.ts

@@ -13,6 +13,7 @@ import { issue_bug_label_rule } from './issue-bug-label'
 import { issue_fold } from './issue-fold'
 import { issue_scout } from './issue-scout'
 import { josh_git_bare } from './josh-git-bare'
+import { lane_background } from './lane-background'
 import { lane_carry_conflict } from './lane-carry-conflict'
 import { lane_interactive_ask } from './lane-interactive-ask'
 import { lane_park } from './lane-park'
@@ -360,6 +361,15 @@ const DELIVERED_RULES: ReadonlyArray<DeliveredRule> = [
 	// verdict is `required`; in the hermetic non-repo suite the git read fails to `exempt`, so
 	// `test-declared` claims nothing and the "exactly one rule" invariant over `run-tail`'s fixture holds.
 	test_declared_commit.ROW,
+	// **The long-running josh command a lane child backgrounds and loses** (joshuafolkken/kit#2704). A
+	// headless child's background tasks die with its turn, so a backgrounded `josh gate` / `git` /
+	// `followup` is killed before it reports; this refuses the launch and hands back `josh ship
+	// --detach`, whose supervisor outlives the turn. **Listed before `run-tail`, whose push it claims in
+	// a child**: that row answers a foreground push with "reissue it backgrounded", the reissue this row
+	// refuses, so a child is sent to the detached ship on its first refusal instead of through both.
+	// Outside a child it claims nothing. A backgrounded bare `josh git` also trips `josh-git-bare`
+	// below; this row wins, and `ship --detach` satisfies both. It fires on every occurrence.
+	lane_background.ROW,
 	// **The one row whose trigger reads a field of the input beside the command**, so it supplies its
 	// own tool-name check rather than going through `on_bash_command`: a push step already issued with
 	// `run_in_background` is the rule obeyed, and refusing it would charge a run for doing the right

package/scripts/rules/lane-background.ts

@@ -0,0 +1,111 @@
+import { cost_blocks } from '#scripts/cost-runtime/cost-blocks'
+import { lane_child_marker } from '#scripts/lane/lane-child-marker'
+import { json_value } from '#scripts/lib/json-value'
+import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
+import { time_shell } from '#scripts/time-runtime/time-shell'
+import { time_transcript_line } from '#scripts/time-runtime/time-transcript-line'
+import { run_tail } from './run-tail'
+
+// A dispatched lane child is stopped from backgrounding a long-running josh command (joshuafolkken/kit#2704).
+//
+// **A headless child's turn-end is its process's end.** A lane child runs as `claude -p`, and there the
+// background Bash tasks die with the turn — so "a background command's exit re-invokes the session"
+// (`background-commands.md`) does not hold. joshuafolkken/kit#2457 refused a non-detached `josh ship`
+// for exactly that reason, but only `ship`: the #2606 child backgrounded `pnpm josh gate && pnpm josh git
+// -y …` directly, ended its turn, and the gate died at `exit code 143` with the implementation, the
+// scoped checks, a review round and the live verification all done — parked instead of merged.
+//
+// **So the refusal is put at the launch, and it names the detached route.** The region from the gate to
+// the merge belongs to `pnpm josh ship --detach` in a child (`chain-rule.md` step 0), whose supervisor
+// outlives the turn. `ship` itself is not in the set: #2457 already detaches it implicitly in a child.
+//
+// **Its stop-time half reads the same fact from the other side.** A backgrounded task the transcript
+// launched but never saw finish is still running, and in a child the stop about to happen kills it —
+// so the `Stop` hook sends the child back to wait or detach rather than asking for a notify
+// (`stop-rules.ts`). The launch and finish ids are `time_transcript_line`'s, never re-parsed here.
+
+// The josh subcommands that run long enough to be backgrounded, as `time_shell` names them — canonical,
+// so the `ga` / `g` / `fu` aliases are covered by the one spelling.
+const LONG_RUNNING_COMMANDS: ReadonlySet<string> = new Set(
+	['gate', 'git', 'followup'].map((name) => `${time_shell.JOSH_PREFIX}${name}`),
+)
+
+const BACKGROUND_KEY = 'run_in_background'
+
+function is_backgrounded(input: unknown): boolean {
+	return json_value.is_record(input) && input[BACKGROUND_KEY] === true
+}
+
+function runs_long_command(command: string): boolean {
+	return time_shell.josh_commands_of(command).some((name) => LONG_RUNNING_COMMANDS.has(name))
+}
+
+// The call's own fields alone: a backgrounded Bash call that runs a long josh command, or the push step
+// in either spelling. A child's foreground push is claimed too, because `run-tail` would otherwise answer
+// it with "reissue it backgrounded" — the one reissue this row then refuses — so the child is handed the
+// detached route on its first refusal rather than two contradictory ones.
+function is_candidate(call: GuardedCall): boolean {
+	if (run_tail.is_push_step_call(call)) return true
+	if (call.name !== cost_blocks.BASH_TOOL || !is_backgrounded(call.input)) return false
+
+	return runs_long_command(time_shell.bash_command(call.input))
+}
+
+// True when this session is a dispatched lane child backgrounding a long-running josh command. The call's
+// own fields are tested first, so the dispatch mark is read only on the handful of calls that match.
+function is_background_long_run(
+	call: GuardedCall,
+	is_lane_child: () => boolean = () => lane_child_marker.is_child_of(process.cwd()),
+): boolean {
+	return is_candidate(call) && is_lane_child()
+}
+
+// The background tasks the transcript tail launched and never saw finish. A launch is read off its own
+// tool result and a finish off the harness notice, both by `time_transcript_line`.
+function pending_background_ids(tail: string): ReadonlyArray<string> {
+	const lines = tail.split('\n').map((line) => time_transcript_line.parse_line(line))
+	const finished = new Set(lines.map((line) => line?.finished_background ?? ''))
+	const launched = lines.flatMap((line) => line?.blocks.map((block) => block.background_id) ?? [])
+
+	return launched.filter((id) => id !== '' && !finished.has(id))
+}
+
+const LANE_BACKGROUND_REASON =
+	'⛔ lane background: this session is a dispatched lane child (`JOSH_LANE_CHILD`), a headless ' +
+	'`claude -p` process whose background Bash tasks are killed when the turn ends — so a backgrounded ' +
+	'`josh gate` / `josh git` / `josh followup` never re-invokes you; it dies at `exit code 143` ' +
+	'(joshuafolkken/kit#2704, measured on the #2606 child: implementation, review and live verification ' +
+	'done, the run parked instead of merged). Hand the gate-to-merge region to the detached supervisor ' +
+	'instead: `pnpm josh ship --detach --review "<title> #<N>"` (add `--cite <N>`), then end the turn on ' +
+	'`launched` / `busy` — `.claude/skills/workflow-commands/chain-rule.md` step 0 is the single source. A ' +
+	'single check you must read before continuing runs in the foreground within the tool timeout; the ' +
+	'commit-push step does not — in a child it too belongs to the detached ship, in either spelling. This ' +
+	'rule fires on every occurrence, not once per run.'
+
+const LANE_BACKGROUND_STOP_REASON =
+	'⛔ lane background stop: this is a dispatched lane child (`JOSH_LANE_CHILD`) and a background task ' +
+	'it launched has not finished — ending this headless turn kills it, and nothing re-invokes you ' +
+	'afterwards (joshuafolkken/kit#2704). Do not send a notification and do not stop: wait for the task ' +
+	'in the foreground and act on its result, or re-issue the work through `pnpm josh ship --detach`, ' +
+	'whose supervisor outlives the turn (`.claude/skills/workflow-commands/chain-rule.md` step 0). Do ' +
+	'not repeat your previous reply.'
+
+// The row itself, so `delivered-rules.ts` spreads one entry. It fires on every occurrence (`decide`
+// returns true): a child must never background these, so the route is always the detached ship, never
+// a reissue. It declares no `keeps`: the detached ship is a different command, not this call made right.
+const ROW = {
+	id: 'lane-background',
+	is_trigger: (call: GuardedCall): boolean => is_background_long_run(call),
+	reason: LANE_BACKGROUND_REASON,
+	decide: (): boolean => true,
+}
+
+const lane_background = {
+	LANE_BACKGROUND_REASON,
+	LANE_BACKGROUND_STOP_REASON,
+	ROW,
+	is_background_long_run,
+	pending_background_ids,
+}
+
+export { lane_background }

package/scripts/rules/stop-rules.ts

@@ -2,6 +2,7 @@ import { hook_decision } from '#scripts/josh/hook-decision'
 import { z } from 'zod'
 import { filing_offer } from './filing-offer'
 import { issue_citation } from './issue-citation'
+import { lane_background } from './lane-background'
 import { reply_language } from './reply-language'
 
 // The stop-time rules, delivered on the `Stop` hook (joshuafolkken/kit#2121, joshuafolkken/kit#2422,
@@ -66,6 +67,9 @@ interface StopContext {
 	headless_refusals: number
 	// This session is a dispatched lane child for this checkout — `lane_child_marker.is_child_of`.
 	lane_child: boolean
+	// A background task this run launched has not finished — `lane_background.pending_background_ids`
+	// over the transcript tail (joshuafolkken/kit#2704).
+	background_pending: boolean
 	// The resolved `JOSH_SESSION_LANG` — `session_language.resolve_session_lang` (joshuafolkken/kit#2470).
 	session_lang: string
 }
@@ -256,10 +260,19 @@ function count_headless_refusals(tail: string): number {
 	return tail.slice(Math.max(last_wait, 0)).split(HEADLESS_WAIT_MARKER).length - 1
 }
 
-// The two hold rules, notify ahead of release — behind the lane index route (joshuafolkken/kit#2445),
-// since the notify they would ask for announces a pause the run has no reason to take.
+// **A lane child with a task still running is sent back to wait, not to notify** (joshuafolkken/kit#2704).
+// Its turn-end kills the task, so the notify the hold rules would ask for announces a stop that loses
+// the work; the #2606 child obeyed exactly that and its gate died at `exit code 143`.
+function needs_background_wait(context: StopContext): boolean {
+	return context.lane_child && context.background_pending
+}
+
+// The two hold rules, notify ahead of release — behind the lane index route (joshuafolkken/kit#2445)
+// and the lane background wait (joshuafolkken/kit#2704), since the notify they would ask for announces
+// a pause the run has no reason to take.
 function hold_reason(context: StopContext): string | undefined {
 	if (needs_index_route(context)) return LANE_INDEX_REASON
+	if (needs_background_wait(context)) return lane_background.LANE_BACKGROUND_STOP_REASON
 	if (needs_notify(context)) return STOP_NOTIFY_REASON
 	if (needs_release(context)) return HOLD_RELEASE_REASON
 

package/scripts/run/run-carry-flush.ts

@@ -1,3 +1,4 @@
+import { PORCELAIN_FLAG, UNTRACKED_FILES_FLAG } from '#scripts/git/constants'
 import { git_spawn } from '#scripts/git/git-spawn'
 import { josh_command } from '#scripts/josh/josh-run'
 import { observation_ledger } from '#scripts/observations/observation-ledger'
@@ -31,13 +32,7 @@ const FAILURE_NOTE =
 
 async function has_pending_append(): Promise<boolean> {
 	const root = observation_ledger_home.ledger_root()
-	const status = await git_spawn.read([
-		'-C',
-		root,
-		'status',
-		'--porcelain',
-		'--untracked-files=normal',
-	])
+	const status = await git_spawn.read(['-C', root, 'status', PORCELAIN_FLAG, UNTRACKED_FILES_FLAG])
 
 	return observation_ledger.has_pending_append(status)
 }

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

@@ -2,6 +2,7 @@
 import { fileURLToPath } from 'node:url'
 import { run_hold, type HoldRead, type RunHold } from './run-hold'
 import { run_preflight, type PreflightDecision } from './run-preflight'
+import { run_tidy_cli } from './run-tidy-cli'
 
 // `josh run:hold [<N>]` and `josh run:release [<N> | --force]` — the working-tree guard the typed
 // entry points ask before they start (joshuafolkken/kit#1091).
@@ -28,6 +29,10 @@ import { run_preflight, type PreflightDecision } from './run-preflight'
 // The contract is `epic:next`'s: **standard output carries exactly one token** — `hold`, `busy` or
 // `unknown` — and every explanation goes to standard error, so `answer=$(pnpm josh run:hold 1091)`
 // captures something a loop can branch on.
+//
+// **A successful claim then sweeps merged residue** — `run:tidy` (joshuafolkken/kit#2701). After the
+// claim rather than before it: the sweep may append to the primary checkout's observation ledger, and
+// doing that ahead of the preflight would turn a clean primary checkout into a `reclaim`.
 
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
@@ -181,9 +186,12 @@ async function claim(target: string, issue: string, is_linked: boolean): Promise
 
 	if (blocked !== undefined) return report_busy(blocked)
 
-	if (read.kind === 'stale') return replace_stale(target, issue, read.hold)
+	const code =
+		read.kind === 'stale' ? replace_stale(target, issue, read.hold) : take_free_tree(target, issue)
 
-	return take_free_tree(target, issue)
+	if (code === SUCCESS_EXIT_CODE) await run_tidy_cli.sweep()
+
+	return code
 }
 
 function remove_record(target: string, was_present: boolean): number {

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

@@ -0,0 +1,50 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { issue_merged } from '#scripts/issue/issue-merged'
+import { run_tidy } from './run-tidy'
+import { run_tidy_lanes, type IsMerged } from './run-tidy-lanes'
+import { run_tidy_stashes } from './run-tidy-stashes'
+
+// `josh run:tidy` — sweep what merged work left behind at a run's start (joshuafolkken/kit#2701): the
+// lanes still holding a seat after their issue merged, and the stashes whose issues are all merged.
+// Both used to wait for a person — `lane:list` flagged a merged lane, `run:carry --end` printed the
+// closed-issue stashes — and a batch ran with two of six seats held by finished work until someone did.
+//
+// `run:hold` calls `sweep` once a claim succeeds, so every `fullrun` / `halfrun` start runs it; a
+// `backlogrun` runs the command itself in its once-per-repository preparation, beside `lane:prune`.
+// **The sweep never fails the run that called it**: the report goes to standard error, where
+// `run:hold`'s one-token standard output is not disturbed, and a failed read is a note, not an exit.
+
+const FAILURE_NOTE = 'run:tidy could not finish; merged lanes and stashes may remain:'
+
+// One read per issue across both halves — a lane and its stash usually name the same one.
+function memoized(read: IsMerged): IsMerged {
+	const answers = new Map<string, Promise<boolean>>()
+
+	return async function read_once(issue: string): Promise<boolean> {
+		const cached = answers.get(issue) ?? read(issue)
+
+		answers.set(issue, cached)
+
+		return await cached
+	}
+}
+
+async function sweep(): Promise<void> {
+	try {
+		const read_merged = memoized(issue_merged.read_merged)
+		const lanes = await run_tidy_lanes.tidy_lanes(read_merged)
+		const stashes = await run_tidy_stashes.tidy_stashes(read_merged)
+		const report = run_tidy.format_report([...lanes, ...stashes])
+
+		if (report !== undefined) console.error(report)
+	} catch (error) {
+		console.error(FAILURE_NOTE, error)
+	}
+}
+
+const run_tidy_cli = { sweep }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await sweep()
+
+export { run_tidy_cli }