@joshuafolkken/kit 1.921.0 → 1.947.0

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-step-cli.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
+import { agent_role_profile } from '#scripts/agent/agent-role-profile'
 import { doctor_consumer } from '#scripts/doctor/doctor-consumer'
 import { hook_decision } from '#scripts/josh/hook-decision'
 import { find_package_directory } from '#scripts/josh/josh-logic'
@@ -29,6 +30,7 @@ const RETROSPECTIVE_ENV_KEY = 'JOSH_RETROSPECTIVE'
 interface RunReads {
 	carry_kind: CarryRead['kind']
 	is_retrospective_done: boolean
+	is_at_cut_cap: boolean
 	last_event: string | undefined
 }
 
@@ -36,7 +38,12 @@ interface RunReads {
 // directory that cannot be read leaves the position unknowable, which `next_action` answers `unknown`.
 function read_run(directory: string | undefined, issue_number: string): RunReads {
 	if (directory === undefined) {
-		return { carry_kind: 'unreadable', is_retrospective_done: false, last_event: undefined }
+		return {
+			carry_kind: 'unreadable',
+			is_retrospective_done: false,
+			is_at_cut_cap: false,
+			last_event: undefined,
+		}
 	}
 
 	const carry = run_carry.read_carry(run_carry.carry_path(directory))
@@ -55,6 +62,7 @@ function read_run(directory: string | undefined, issue_number: string): RunReads
 	return {
 		carry_kind: carry.kind,
 		is_retrospective_done: run_carry.retrospective_done_of(carry),
+		is_at_cut_cap: carry.kind === 'carried' && run_carry.is_at_cut_cap(carry.carry),
 		last_event: last?.kind,
 	}
 }
@@ -72,10 +80,12 @@ async function gather(issue_number: string): Promise<StepInput> {
 		last_event: run_reads.last_event,
 		carry_kind: run_reads.carry_kind,
 		is_retrospective_done: run_reads.is_retrospective_done,
+		is_at_cut_cap: run_reads.is_at_cut_cap,
 		is_lane_child: lane_child_marker.is_child_of(process.cwd()),
 		is_consumer: doctor_consumer.is_kit_consumer(find_package_directory(process.cwd())),
 		is_retrospective_enabled: hook_decision.is_switch_opt_in(RETROSPECTIVE_ENV_KEY),
 		has_changes: parts.has_changes,
+		has_completion_callback: agent_role_profile.has_completion_callback(),
 	}
 }
 

package/scripts/run/run-step.ts

@@ -118,6 +118,13 @@ interface StepInput extends PreInput {
 	// are opt-in — so a run that leaves the variable unset never prints the retrospective step, while the
 	// retrospective's own logic is untouched and `pnpm josh retrospective` still runs by hand.
 	is_retrospective_enabled: boolean
+	// Whether this session is woken when a background command it started completes, read by the CLI from
+	// the session's own environment (joshuafolkken/kit#2653). A parent without the callback cannot wait
+	// on its lanes except by polling, so it hands the run to the supervisor instead of waiting.
+	has_completion_callback: boolean
+	// Whether the carried invocation has already taken its maximum cuts, read off the carry record by the
+	// CLI (joshuafolkken/kit#2346). At the cap `run:carry --cut` refuses, so the hand-off is not offered.
+	is_at_cut_cap: boolean
 }
 
 interface StepAction {
@@ -134,10 +141,9 @@ function command(line: string): StepAction {
 }
 
 // The action for each event a run can be positioned at, keyed on the newest one. Each dispatches to the
-// command that owns that phase; `child-launch` is the one position with no command to run — the parent
-// waits for its child. `stop` and `drain` are handled apart in `stop_action` / `drain_action`, because
-// whether either still owes a retrospective needs more than the issue number. A merge and an outage share a next step: `run:merge`
-// classifies both, including the outage's stop condition.
+// command that owns that phase. `stop`, `drain` and `child-launch` are handled apart in
+// `FULL_INPUT_ACTIONS`, because each needs more than the issue number. A merge and an outage share a
+// next step: `run:merge` classifies both, including the outage's stop condition.
 const KIND = run_event_stream.EVENT_KIND
 // A park and a stall share this next step: both mean runnable work is waiting to be offered
 // (joshuafolkken/kit#2359), so both are pointed at the backlog.
@@ -149,7 +155,6 @@ const EVENT_ACTIONS: Record<string, (issue_number: string) => StepAction> = {
 	[KIND.OUTAGE]: (issue_number) => command(`pnpm josh run:merge ${issue_number}`),
 	[KIND.PARK]: () => command(OFFER_BACKLOG),
 	[KIND.CUT]: (issue_number) => command(`pnpm josh run:cut --resume ${issue_number}`),
-	[KIND.CHILD_LAUNCH]: () => verdict(WAIT),
 	// A stall is undispatched ready work with a free lane, so its next step is exactly a park's: offer
 	// the backlog. The detector only reports the stall; reading it here as a dispatch is what turns the
 	// report into the action that resolves it.
@@ -197,12 +202,34 @@ function drain_action(input: StepInput): StepAction {
 	return is_retrospective_owed(input) ? command(RETROSPECTIVE_COMMAND) : verdict(WAIT)
 }
 
-// The two positions whose action needs the whole input rather than the issue number — a stop and a
-// drain both turn on whether the retrospective is still owed. Kept in a map so `next_action` dispatches
-// them in one branch rather than one `if` apiece (`is_retrospective_owed` is the shared gate).
+// The hand-off a `backlogrun` parent without a completion callback takes right after dispatching
+// (joshuafolkken/kit#2653). It is the existing merge-time cut, so the ownership check and the cut cap
+// apply unchanged, and the supervisor's driver adopts the in-flight lanes from their `child-launch`
+// events.
+const HAND_OFF_COMMAND = 'pnpm josh run:carry --cut --owner "$PPID"'
+
+// After a dispatch the parent waits for its child — where waiting is free. A session the completion
+// does not re-invoke could only wait by polling, each poll a model call over its whole context, so a
+// `backlogrun` parent there hands the carry record to the supervisor instead. A lane child and a run
+// with no carry record have nothing to hand off, so both still wait; so does a run at the cut cap, whose
+// cut would be refused on every ask and leave the carry record with nobody.
+function can_hand_off(input: StepInput): boolean {
+	if (input.is_lane_child || input.is_at_cut_cap) return false
+
+	return input.carry_kind === 'carried' && !input.has_completion_callback
+}
+
+function child_launch_action(input: StepInput): StepAction {
+	return can_hand_off(input) ? command(HAND_OFF_COMMAND) : verdict(WAIT)
+}
+
+// The positions whose action needs the whole input rather than the issue number — a stop and a drain
+// both turn on whether the retrospective is still owed, a child launch on whether waiting is free. Kept
+// in a map so `next_action` dispatches them in one branch rather than one `if` apiece.
 const FULL_INPUT_ACTIONS: Record<string, (input: StepInput) => StepAction> = {
 	[KIND.STOP]: stop_action,
 	[KIND.DRAIN]: drain_action,
+	[KIND.CHILD_LAUNCH]: child_launch_action,
 }
 
 // An event the table does not name leaves the position unknown rather than guessing a next step. A
@@ -275,6 +302,7 @@ function next_action(input: StepInput): StepAction {
 const run_step = {
 	ALREADY_DONE,
 	EXPIRED_DECISION,
+	HAND_OFF_COMMAND,
 	HUMAN_REVIEW,
 	IMPLEMENT,
 	KEEP_WORK,

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 }