@joshuafolkken/kit 1.1094.0 → 1.1128.0

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").'
 

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

@@ -76,17 +76,13 @@ type Request =
 const READ_REQUEST: Request = { kind: 'read' }
 
 function read_arguments(argv: ReadonlyArray<string>): ParsedValues | undefined {
-	return cli_flags.parse_or_undefined({ args: [...argv], options: OPTIONS, strict: true })?.values
-}
-
-function text_of(value: OptionValue): string | undefined {
-	return typeof value === 'string' ? value : undefined
+	return cli_flags.values_of(argv, OPTIONS)
 }
 
 // Absent is zero; present but not a count is `undefined`, which invalidates the whole invocation
 // rather than quietly counting nothing.
 function to_count(value: OptionValue): number | undefined {
-	const text = text_of(value)
+	const text = cli_flags.string_of(value)
 
 	if (text === undefined) return NO_INCREMENT
 
@@ -99,7 +95,7 @@ function to_count(value: OptionValue): number | undefined {
 // than a zero: there is no issue to record, which is a different fact from recording issue zero. A
 // present-but-malformed value invalidates the whole invocation, exactly as a bad `--merged` does.
 function to_done(value: OptionValue): Pick<CarryChange, 'done'> | undefined {
-	const text = text_of(value)
+	const text = cli_flags.string_of(value)
 
 	if (text === undefined) return {}
 
@@ -165,7 +161,7 @@ function group_count(values: ParsedValues): number {
 // the record simply declares no owner and every standing record reads as not provably live, which
 // refuses rather than resumes.
 function to_owner(value: OptionValue): CarryOwner | undefined {
-	const text = text_of(value)
+	const text = cli_flags.string_of(value)
 
 	if (text === undefined) return run_carry.NO_OWNER
 
@@ -179,7 +175,7 @@ function to_owner(value: OptionValue): CarryOwner | undefined {
 // A non-empty `--summary`, or nothing. An empty string is nothing here, so it reads as absent and the
 // pairing check below refuses it against `--retrospective`.
 function summary_text(values: ParsedValues): string | undefined {
-	const summary = text_of(values.summary)
+	const summary = cli_flags.string_of(values.summary)
 
 	return summary === undefined || summary === '' ? undefined : summary
 }
@@ -220,17 +216,17 @@ function to_claim_request(
 }
 
 function to_other_request(values: ParsedValues, owner: CarryOwner): Request | undefined {
-	if (values.end === true) return { kind: 'end', stopped: text_of(values.stopped) }
+	if (values.end === true) return { kind: 'end', stopped: cli_flags.string_of(values.stopped) }
 
 	return has_count(values) ? to_count_request(values, owner) : READ_REQUEST
 }
 
 function to_named_request(values: ParsedValues, owner: CarryOwner): Request | undefined {
-	const begun = text_of(values.begin)
+	const begun = cli_flags.string_of(values.begin)
 
 	if (begun !== undefined) return to_claim_request(begun, owner, false)
 
-	const adopted = text_of(values.resume)
+	const adopted = cli_flags.string_of(values.resume)
 
 	if (adopted !== undefined) return to_claim_request(adopted, owner, true)
 

package/scripts/run/run-cut-args.ts

@@ -47,12 +47,7 @@ type Request =
 	| { kind: 'end' }
 
 function read_arguments(argv: ReadonlyArray<string>): ParsedValues | undefined {
-	return cli_flags.parse_or_undefined({
-		args: [...argv],
-		options: OPTIONS,
-		strict: true,
-		allowPositionals: true,
-	})
+	return cli_flags.arguments_of(argv, OPTIONS)
 }
 
 // The issue is the sole positional, and it must be a real issue number: a cut relaunches

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

@@ -56,10 +56,6 @@ interface ParsedArguments {
 	values: ParsedValues
 }
 
-function read_arguments(argv: ReadonlyArray<string>): ParsedArguments | undefined {
-	return cli_flags.parse_or_undefined({ args: [...argv], options: OPTIONS, allowPositionals: true })
-}
-
 function is_valid(parsed: ParsedArguments): boolean {
 	return (
 		parsed.positionals.length === 1 &&
@@ -78,7 +74,7 @@ function to_request(parsed: ParsedArguments): EndingRequest {
 }
 
 function parse_request(argv: ReadonlyArray<string>): EndingRequest | undefined {
-	const parsed = read_arguments(argv)
+	const parsed = cli_flags.arguments_of(argv, OPTIONS)
 
 	if (parsed === undefined || !is_valid(parsed)) return undefined
 

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

@@ -4,6 +4,7 @@ import { josh_command } from '#scripts/josh/josh-run'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
 import { run_cut_report } from './run-cut-report'
 import { run_entry, type EntryParts } from './run-entry'
+import { run_entry_stop } from './run-entry-stop'
 import { run_halfrun_resume } from './run-halfrun-resume'
 import { run_hold_cli } from './run-hold-cli'
 import { run_next } from './run-next'
@@ -40,6 +41,7 @@ const NEWLINE = '\n'
 const HOLD_STOP_NOTE =
 	'(tree not held — see the reason above; clean up and retry, or release with `pnpm josh run:release`)'
 const COST_STOP_NOTE = '(session budget spent — see the figure above; resume in a fresh session)'
+const { BUDGET_REASON, HOLD_REASON } = run_entry_stop
 const HALFRUN_RESUME_TOKEN = 'halfrun'
 
 // Exactly one issue number, or the call is refused — `run:entry` opens one run, and a second number
@@ -135,6 +137,23 @@ function stop_report(issue_number: string, hold: string, cost: string, report: s
 	return emit({ issue_number, hold, cost, verdict: run_entry.NO_VERDICT, report })
 }
 
+// A stop this command decided carries its own chores (joshuafolkken/kit#3099): the `confirmation`
+// Telegram always, and the release where this call claimed the hold — `run_entry_stop` says why.
+interface StopCall {
+	parts: Pick<EntryParts, 'issue_number' | 'hold' | 'cost' | 'report'>
+	command: StageCommand
+	reason: string
+	should_release: boolean
+}
+
+async function stop_run({ parts, command, reason, should_release }: StopCall): Promise<number> {
+	const code = stop_report(parts.issue_number, parts.hold, parts.cost, parts.report)
+
+	await run_entry_stop.stop({ issue_number: parts.issue_number, command, reason, should_release })
+
+	return code
+}
+
 interface Resume {
 	token: string
 	code: number
@@ -166,16 +185,22 @@ function resume_report(issue_number: string, resume: Resume): number {
 // to and including implementation. **A `prrun` stopped before its merge is resumed the same way**
 // (joshuafolkken/kit#3023), under the token that says what is left of it.
 async function resume_stopped(
-	issue_number: string,
+	{ issue_number, command }: EntryRequest,
 	token: string,
 	stopped_run: { adopt: (issue: string) => Promise<boolean> },
 ): Promise<number> {
 	const cost = await check_cost()
 
-	if (cost === run_entry.COST_OVER) return stop_report(issue_number, token, cost, COST_STOP_NOTE)
+	if (cost === run_entry.COST_OVER) {
+		const parts = { issue_number, hold: token, cost, report: COST_STOP_NOTE }
+
+		return await stop_run({ parts, command, reason: BUDGET_REASON, should_release: false })
+	}
 
 	if (!(await stopped_run.adopt(issue_number))) {
-		return stop_report(issue_number, run_hold_cli.BUSY_VERDICT, cost, HOLD_STOP_NOTE)
+		const parts = { issue_number, hold: run_hold_cli.BUSY_VERDICT, cost, report: HOLD_STOP_NOTE }
+
+		return await stop_run({ parts, command, reason: HOLD_REASON, should_release: false })
 	}
 
 	console.info(`entry #${issue_number} — resume: ${token}`)
@@ -186,17 +211,17 @@ async function resume_stopped(
 // The stopped run a decision picks up: a `halfrun` stop resumes at the gate, a `prrun` stop at
 // `followup` under its own token. `undefined` for any other start, so the ordinary claim decides.
 async function resume_any(
-	issue_number: string,
+	request: EntryRequest,
 	decision: StageDecision,
 	stage: StageRead,
 ): Promise<number | undefined> {
 	if (decision.state === run_stage.HALFRUN_STOPPED) {
-		return await resume_stopped(issue_number, HALFRUN_RESUME_TOKEN, run_halfrun_resume)
+		return await resume_stopped(request, HALFRUN_RESUME_TOKEN, run_halfrun_resume)
 	}
 
 	return stage.prrun_token === undefined
 		? undefined
-		: await resume_stopped(issue_number, stage.prrun_token, run_prrun_resume)
+		: await resume_stopped(request, stage.prrun_token, run_prrun_resume)
 }
 
 // **A command whose stopping point the issue has already reached redoes nothing** (joshuafolkken/kit#3042)
@@ -210,12 +235,18 @@ async function claim_run({ issue_number, command }: EntryRequest): Promise<numbe
 	const hold = await claim_hold(issue_number, command)
 
 	if (hold !== run_hold_cli.HOLD_VERDICT) {
-		return stop_report(issue_number, hold, run_entry.COST_SKIPPED, HOLD_STOP_NOTE)
+		const parts = { issue_number, hold, cost: run_entry.COST_SKIPPED, report: HOLD_STOP_NOTE }
+
+		return await stop_run({ parts, command, reason: HOLD_REASON, should_release: false })
 	}
 
 	const cost = await check_cost()
 
-	if (cost === run_entry.COST_OVER) return stop_report(issue_number, hold, cost, COST_STOP_NOTE)
+	if (cost === run_entry.COST_OVER) {
+		const parts = { issue_number, hold, cost, report: COST_STOP_NOTE }
+
+		return await stop_run({ parts, command, reason: BUDGET_REASON, should_release: true })
+	}
 
 	const reads = await gather_reads(issue_number)
 
@@ -248,7 +279,7 @@ async function open_run(request: EntryRequest): Promise<number> {
 
 	if (command === run_stage.KICKOFF || is_settled(decision)) return SUCCESS_EXIT_CODE
 
-	return (await resume_any(issue_number, decision, stage)) ?? (await claim_run(request))
+	return (await resume_any(request, decision, stage)) ?? (await claim_run(request))
 }
 
 async function run(argv: ReadonlyArray<string>): Promise<number> {

package/scripts/run/run-entry-stop.ts

@@ -0,0 +1,104 @@
+import { josh_command } from '#scripts/josh/josh-run'
+import { telegram_notify } from '#scripts/notify/telegram-notify'
+import { lane_park } from '#scripts/rules/lane-park'
+
+// What `run:entry` does on the way out of a stop it decided itself (joshuafolkken/kit#3099).
+//
+// **The stop's chores used to be the agent's to remember, and the `Stop` hook was what reminded it.**
+// `fullrun.md` step 3 asked the agent, on an `over` budget, to send the `confirmation` Telegram and then
+// run `pnpm josh run:release` — two calls after a command had already decided the run was over. Across
+// eleven measured sessions the hook sent a reply back five times for exactly those two calls, each one a
+// further turn re-reading the whole context. The command that decides the stop knows everything the
+// chores need, so it does them, and the hook stays a safety net that a normal run never trips.
+//
+// **The release is the claim's own undo, and only where this call made the claim.** A resume over a
+// stopped `halfrun` / `prrun` stops on the budget before adopting anything, and the hold there is the
+// stopped run's — kept on purpose over its verified diff — so that stop notifies and releases nothing.
+// A `busy` / `unknown` hold is another run's, or none at all, so it is never released here either.
+//
+// **A dispatched lane child sends no Telegram from here.** Its stop must park the Issue before it
+// notifies, and `lane_park`'s guard delivers that rule at the `josh notify` call — a Telegram sent from
+// inside this command would pass that guard by and satisfy the `Stop` hook with no park behind it.
+
+interface StopNotice {
+	issue_number: string
+	command: string
+	reason: string
+	should_release: boolean
+}
+
+interface StopPorts {
+	notify: (input: { issue_title: string; body: string; recovery: string }) => Promise<boolean>
+	release: (issue_number: string) => Promise<boolean>
+	is_parking_child: () => boolean
+}
+
+const RECOVERY = 'If this did not arrive, the run:entry output in the session names the stop.'
+const NOTIFY_FAILED_NOTE =
+	'(the confirmation Telegram could not be sent — send it with `pnpm josh notify --task-type confirmation` before stopping)'
+const RELEASED_NOTE = '(hold released by run:entry — the tree is free for the resume)'
+const RELEASE_FAILED_NOTE =
+	'(the hold could not be released — run `pnpm josh run:release` before stopping)'
+const should_forward_stderr = true
+const SUCCESS_EXIT_CODE = 0
+
+const BUDGET_REASON = 'the session budget is spent'
+const HOLD_REASON = 'the working tree is not held for this run — see the run:entry output'
+
+async function release(issue_number: string): Promise<boolean> {
+	const released = await josh_command.josh_run(['run:release', issue_number], should_forward_stderr)
+
+	return released.code === SUCCESS_EXIT_CODE
+}
+
+function is_parking_child(): boolean {
+	return lane_park.is_parking_child()
+}
+
+const DEFAULT_PORTS: StopPorts = { notify: telegram_notify.confirm, release, is_parking_child }
+
+function body_of(notice: StopNotice): string {
+	return `${notice.command} #${notice.issue_number} stopped at entry: ${notice.reason}.\nResume with \`${notice.command} #${notice.issue_number}\`.`
+}
+
+// The release runs first, so the resume the Telegram names finds the tree free when a person acts on it.
+// The marker line is printed only for a Telegram that went out: the `Stop` hook reads it as the notify,
+// and a failed send has to leave the hook still asking for one. The released note, likewise, is printed
+// only for a release that succeeded, so a failed one leaves the agent still asked to release.
+async function release_claim(notice: StopNotice, ports: StopPorts): Promise<void> {
+	if (!notice.should_release) return
+
+	const is_released = await ports.release(notice.issue_number)
+
+	console.info(is_released ? RELEASED_NOTE : RELEASE_FAILED_NOTE)
+}
+
+async function notify_stop(notice: StopNotice, ports: StopPorts): Promise<void> {
+	if (ports.is_parking_child()) return
+
+	const is_sent = await ports.notify({
+		issue_title: `${notice.command} #${notice.issue_number} stopped`,
+		body: body_of(notice),
+		recovery: RECOVERY,
+	})
+
+	console.info(is_sent ? lane_park.COMMAND_NOTIFY_MARKER : NOTIFY_FAILED_NOTE)
+}
+
+async function stop(notice: StopNotice, ports: StopPorts = DEFAULT_PORTS): Promise<void> {
+	await release_claim(notice, ports)
+	await notify_stop(notice, ports)
+}
+
+const run_entry_stop = {
+	BUDGET_REASON,
+	HOLD_REASON,
+	NOTIFY_FAILED_NOTE,
+	RELEASED_NOTE,
+	RELEASE_FAILED_NOTE,
+	body_of,
+	stop,
+}
+
+export { run_entry_stop }
+export type { StopNotice, StopPorts }

package/scripts/run/run-event-stream-emit.ts

@@ -1,3 +1,4 @@
+import { error_text } from '#scripts/lib/error-message'
 import { run_carry } from './run-carry'
 import { run_event_scope } from './run-event-scope'
 import { run_event_stream, type RunEvent } from './run-event-stream'
@@ -62,8 +63,10 @@ async function emit_once(kind: string, text: string): Promise<boolean> {
 		if (target === undefined || run_event_stream.read_last(target)?.kind === kind) return false
 
 		return run_event_stream.append(target, kind, text, now_iso()).appended
-	} catch {
+	} catch (error) {
 		// Best-effort: a failed append is dropped rather than raised into the loop's work.
+		error_text.trace_swallowed('run_event_stream_emit.emit_once', error)
+
 		return false
 	}
 }
@@ -98,8 +101,10 @@ async function emit_once_since(kind: string, text: string, reset_kind: string):
 		}
 
 		return run_event_stream.append(target, kind, text, now_iso()).appended
-	} catch {
+	} catch (error) {
 		// Best-effort: a failed append is dropped rather than raised into the caller's work.
+		error_text.trace_swallowed('run_event_stream_emit.emit_once_since', error)
+
 		return false
 	}
 }

package/scripts/run/run-hold.ts

@@ -1,5 +1,6 @@
 import { git_command } from '#scripts/git/git-command'
 import { stamp_file } from '#scripts/josh/stamp-file'
+import { error_text } from '#scripts/lib/error-message'
 import { z } from 'zod'
 
 // joshuafolkken/kit#1091: `epicrun` asks `epic-busy.ts` whether a *repository* already has a child in
@@ -196,7 +197,9 @@ async function is_tree_dirty(directory?: string): Promise<boolean> {
 		const status = await git_command.status(directory)
 
 		return status.trim() !== ''
-	} catch {
+	} catch (error) {
+		error_text.trace_swallowed('run_hold.is_tree_dirty', error)
+
 		return true
 	}
 }

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

@@ -89,10 +89,6 @@ interface ParsedArguments {
 	values: ParsedValues
 }
 
-function read_arguments(argv: ReadonlyArray<string>): ParsedArguments | undefined {
-	return cli_flags.parse_or_undefined({ args: [...argv], options: OPTIONS, allowPositionals: true })
-}
-
 function is_valid_target(parsed: ParsedArguments): boolean {
 	return (
 		parsed.positionals.length === 1 &&
@@ -136,7 +132,7 @@ function to_request(parsed: ParsedArguments): LivenessRequest {
 }
 
 function parse_request(argv: ReadonlyArray<string>): LivenessRequest | undefined {
-	const parsed = read_arguments(argv)
+	const parsed = cli_flags.arguments_of(argv, OPTIONS)
 
 	if (parsed === undefined || !is_valid(parsed)) return undefined