@joshuafolkken/kit 1.1094.0 → 1.1136.0

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

@@ -10,6 +10,7 @@ import {
 	type RunCarry,
 } from './run-carry'
 import { run_carry_args, type CountRequest, type Request } from './run-carry-args'
+import { run_carry_conversation } from './run-carry-conversation'
 import { run_carry_stash } from './run-carry-stash'
 import { run_event_stream } from './run-event-stream'
 import { run_event_stream_emit } from './run-event-stream-emit'
@@ -331,7 +332,8 @@ async function count(
 
 	if (blocked !== undefined) return blocked
 
-	const carry = run_carry.apply_change(target, read.carry, request.change)
+	const owned = run_carry_conversation.reclaim_owner(read.carry, request.owner)
+	const carry = run_carry.apply_change(target, owned, request.change)
 
 	await record_retrospective(request)
 

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

@@ -0,0 +1,94 @@
+import { existsSync, statSync } from 'node:fs'
+import path from 'node:path'
+import { cost_transcript } from '#scripts/cost-runtime/cost-transcript'
+import { own_session } from '#scripts/cost-runtime/own-session'
+import type { CarryOwner, RunCarry } from './run-carry'
+
+// **A conversation outlives its process, so an owner named by a pid alone dies too early**
+// (joshuafolkken/kit#3137). The carry record names the agent process spending the budget, and that is
+// right while the process lives — but an interactive conversation is not its process. On 2026-10-04 a
+// VS Code extension-host restart ended the session's process at 15:17:34 UTC, and the same
+// conversation resumed eighteen seconds later in a new process (`--resume=<id>`), writing on into the
+// same transcript. `run:wake` read the old pid as dead, recovered the record as a crash, and dispatched
+// a second lane child for the issue the conversation was still running.
+//
+// **The transcript is what persists across the restart, so it is the second half of the identity.**
+// Every resume path — the extension's `--resume=<id>`, a person's `claude -c` — appends to the one
+// file named by the session id, and nothing else writes it. So a record also names its owner's
+// transcript, and a dead pid whose transcript was written inside the quiet window below is a
+// conversation still being continued rather than a crash. Matching the transcript is also how the
+// resumed conversation is recognized as the record's own owner, so it can keep counting.
+//
+// **A hand-off ends the conversation's claim.** A record `--cut` handed off is waited on by the pid
+// alone, because the cutting conversation is meant to end there — counted by its transcript, the
+// supervisor would hold every cut for the whole window after the cutting process had already exited.
+
+// How long after its last write a conversation whose process has gone still counts as continuing. It
+// bridges a restart and a resume — measured at eighteen seconds — with room for a person reopening a
+// window, and it is the order of the wake grace window, so a genuine crash is recovered no later than
+// a lost wake would be retried.
+const CONVERSATION_QUIET_MS = 600_000
+
+type Environment = Readonly<Record<string, string | undefined>>
+
+// The calling session's own transcript, or `undefined` outside a session or when its file cannot be
+// found. **The id comes from the environment, which a detached supervisor never inherits**
+// (`agent-session-environment.ts` strips it), so a record the supervisor adopts names no transcript.
+function own_transcript(
+	environment: Environment = process.env,
+	directories: ReadonlyArray<string> = cost_transcript.transcript_directories(process.cwd()),
+): string | undefined {
+	const session_id = own_session.session_id_of(environment)
+
+	if (session_id === undefined) return undefined
+
+	const name = `${session_id}${cost_transcript.TRANSCRIPT_EXTENSION}`
+
+	return directories.map((directory) => path.join(directory, name)).find((file) => existsSync(file))
+}
+
+function modified_ms(transcript: string): number | undefined {
+	try {
+		return statSync(transcript).mtimeMs
+	} catch {
+		return undefined
+	}
+}
+
+function is_recent(modified: number | undefined, now: Date): boolean {
+	return modified !== undefined && now.getTime() - modified <= CONVERSATION_QUIET_MS
+}
+
+function is_conversation_live(
+	carry: RunCarry,
+	now: Date = new Date(),
+	read_modified: (transcript: string) => number | undefined = modified_ms,
+): boolean {
+	if (carry.is_handed_off === true || carry.owner_transcript === undefined) return false
+
+	return is_recent(read_modified(carry.owner_transcript), now)
+}
+
+function is_same_conversation(carry: RunCarry, owner: CarryOwner): boolean {
+	return owner.transcript !== undefined && owner.transcript === carry.owner_transcript
+}
+
+// The record with its owner moved to the caller's process when the caller is the same conversation in
+// a new one, so the record goes on naming a live process once the conversation falls quiet. A record a
+// cut handed off is the successor's to take, never the cutting conversation's to take back.
+function reclaim_owner(carry: RunCarry, owner: CarryOwner): RunCarry {
+	if (carry.is_handed_off === true || !is_same_conversation(carry, owner)) return carry
+	if (owner.pid === carry.owner_pid) return carry
+
+	return { ...carry, owner_pid: owner.pid, owner_start: owner.start }
+}
+
+const run_carry_conversation = {
+	CONVERSATION_QUIET_MS,
+	own_transcript,
+	is_conversation_live,
+	is_same_conversation,
+	reclaim_owner,
+}
+
+export { run_carry_conversation }

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

@@ -0,0 +1,37 @@
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { run_carry, type CarryOwner } from './run-carry'
+import { run_carry_conversation } from './run-carry-conversation'
+
+// **A resumed conversation has to take its record back before it falls quiet** (joshuafolkken/kit#3137).
+// A count moves the owner to the conversation's new process, but a parent waiting on a lane child
+// counts nothing — `lane:await` blocks in the background and the transcript stays unwritten — so a
+// restart followed by a long wait outlasts the quiet window with the record still naming the dead
+// process, and `run:wake` recovers it as a crash. The wait itself is therefore where the parent
+// declares its owner: `lane:await --owner "$PPID"` reclaims the record before it starts waiting.
+
+// Writes the record back under the caller's process when the caller is the record's own conversation
+// in a new one; answers whether it did.
+function reclaim_at(target: string, owner: CarryOwner): boolean {
+	const read = run_carry.read_carry(target)
+
+	if (read.kind !== 'carried') return false
+
+	const reclaimed = run_carry_conversation.reclaim_owner(read.carry, owner)
+
+	if (reclaimed === read.carry) return false
+
+	// Replaced atomically: a `run:wake` reading between an unlink and a write would see no record.
+	stamp_file.replace_stamp(target, reclaimed)
+
+	return true
+}
+
+async function reclaim_carry(owner: CarryOwner): Promise<boolean> {
+	const directory = await run_carry.repository_directory()
+
+	return directory !== undefined && reclaim_at(run_carry.carry_path(directory), owner)
+}
+
+const run_carry_reclaim = { reclaim_at, reclaim_carry }
+
+export { run_carry_reclaim }

package/scripts/run/run-carry.ts

@@ -4,6 +4,7 @@ import { process_identity } from '#scripts/josh/process-identity'
 import { stamp_file } from '#scripts/josh/stamp-file'
 import { z } from 'zod'
 import { run_carry_change } from './run-carry-change'
+import { run_carry_conversation } from './run-carry-conversation'
 import { run_invocation } from './run-invocation'
 
 // joshuafolkken/kit#1714: a `backlogrun` declares a budget — `--max`, `--idle` and the 8-hour
@@ -106,6 +107,9 @@ interface RunCarry {
 	// them apart would be asserting a distinction nothing here can observe.
 	owner_pid?: number | undefined
 	owner_start?: string | undefined
+	// The owner conversation's transcript, which outlives a restart of its process
+	// (`run-carry-conversation.ts`, joshuafolkken/kit#3137). Optional for the same reason as the pid.
+	owner_transcript?: string | undefined
 	// Set by `--cut`, and by nothing else. A crash never reaches `--cut`, which is what makes a
 	// declared cut the only standing record carried without a person deciding.
 	is_handed_off?: boolean | undefined
@@ -129,10 +133,12 @@ interface RunCarry {
 }
 
 // The identity of a process, as `process-identity.ts` keeps it: the pid plus an opaque start-time
-// token, so a reissued pid is never mistaken for the process that wrote the record.
+// token, so a reissued pid is never mistaken for the process that wrote the record — and the
+// transcript of the conversation that process runs, which outlives it (`run-carry-conversation.ts`).
 interface CarryOwner {
 	pid?: number | undefined
 	start?: string | undefined
+	transcript?: string | undefined
 }
 
 // **`resume` is the only one of the four that establishes anything.** The other three are refusals,
@@ -201,6 +207,7 @@ const run_carry_schema = z.object({
 	// which is the not-provably-live answer rather than a live one.
 	owner_pid: z.number().optional(),
 	owner_start: z.string().optional(),
+	owner_transcript: z.string().optional(),
 	is_handed_off: z.boolean().optional(),
 	done: z.array(z.number()).optional(),
 	// Optional, so a record written before the retrospective existed still parses (joshuafolkken/kit#2328).
@@ -256,12 +263,14 @@ function read_carry(target: string, now: Date = new Date()): CarryRead {
 
 // The identity to record for a pid the caller declared. `read_start` is what makes the pair an
 // identity rather than a number; injected in tests so the sandbox branch is exercised without
-// changing the machine's process capabilities.
+// changing the machine's process capabilities. The transcript is the calling session's own — the
+// declared pid is that session's process (`--owner "$PPID"`).
 function owner_of(
 	pid: number,
 	read: (owner_pid: number) => string | undefined = process_identity.read_start,
+	transcript: string | undefined = run_carry_conversation.own_transcript(),
 ): CarryOwner {
-	return { pid, start: read(pid) }
+	return { pid, start: read(pid), transcript }
 }
 
 function fresh_carry(invocation: string, owner: CarryOwner, now: Date): RunCarry {
@@ -275,6 +284,7 @@ function fresh_carry(invocation: string, owner: CarryOwner, now: Date): RunCarry
 		outages: NO_INCREMENT,
 		owner_pid: owner.pid,
 		owner_start: owner.start,
+		owner_transcript: owner.transcript,
 	}
 }
 
@@ -329,6 +339,7 @@ function adopt_carry(
 		...carry,
 		owner_pid: owner.pid,
 		owner_start: owner.start,
+		owner_transcript: owner.transcript,
 		is_handed_off: false,
 	}
 
@@ -340,11 +351,16 @@ function adopt_carry(
 // A live pid with no readable start token is conservatively held rather than replaced. The command
 // cannot prove its generation inside that sandbox, but a false `busy` stops for a person while a
 // false `standing` can put two parents on one budget. A record with no pid still resolves false.
-function is_owner_live(carry: RunCarry): boolean {
-	return process_identity.is_same_process(carry.owner_pid, carry.owner_start) !== false
+// A gone process whose conversation is still being continued is live (`run-carry-conversation.ts`).
+function is_owner_live(carry: RunCarry, now: Date = new Date()): boolean {
+	if (process_identity.is_same_process(carry.owner_pid, carry.owner_start) !== false) return true
+
+	return run_carry_conversation.is_conversation_live(carry, now)
 }
 
 function is_owned_by(carry: RunCarry, owner: CarryOwner): boolean {
+	if (run_carry_conversation.is_same_conversation(carry, owner)) return true
+
 	return carry.owner_pid === owner.pid && carry.owner_start === owner.start
 }
 

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
 

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

@@ -1,11 +1,11 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
-import { parseArgs } from 'node:util'
 import { api_outage } from '#scripts/agent/api-outage'
 import { CONTEXT_CUT_THRESHOLD } from '#scripts/cost-runtime/context-cut-threshold'
 import { issue_closing_pr } from '#scripts/issue/issue-closing-pr'
 import { issue_state_cli } from '#scripts/issue/issue-state-cli'
 import { lane_handoff } from '#scripts/lane/lane-handoff'
+import { cli_flags } from '#scripts/lib/cli-flags'
 import { run_carry, type CarryOwner, type RunCarry } from './run-carry'
 import { run_ending } from './run-ending'
 import { run_event_stream } from './run-event-stream'
@@ -69,14 +69,6 @@ interface ParsedArguments {
 	values: Partial<Record<'epic' | 'output' | 'over' | 'owner' | 'repo', string>>
 }
 
-function read_args(argv: ReadonlyArray<string>): ParsedArguments | undefined {
-	try {
-		return parseArgs({ args: [...argv], options: OPTIONS, allowPositionals: true, strict: true })
-	} catch {
-		return undefined
-	}
-}
-
 // Absent owner is "no owner declared", which the carry guard reads as not provably foreign; a present
 // but malformed pid invalidates the invocation rather than silently counting unguarded.
 function to_owner(raw: string | undefined): CarryOwner | undefined {
@@ -170,7 +162,7 @@ function to_context(parsed: ParsedArguments): MergeContext | undefined {
 }
 
 function parse(argv: ReadonlyArray<string>): MergeContext | undefined {
-	const parsed = read_args(argv)
+	const parsed = cli_flags.arguments_of(argv, OPTIONS)
 
 	return parsed === undefined ? undefined : to_context(parsed)
 }