@joshuafolkken/kit 1.1471.0 → 1.1784.0

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

@@ -0,0 +1,65 @@
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { run_halfrun_resume } from '#scripts/run/run-halfrun-resume'
+import { run_label } from '#scripts/run/run-label'
+import { run_hold } from './run-hold'
+
+// `josh run:hold --adopt <N>` — a `new` run's hand-over once its Issue is filed (joshuafolkken/kit#4156).
+// The unnumbered record is re-keyed in place to `<N>`, so every later stop of the run releases with
+// `run:release <N>` and that release takes `in-progress` back off; the adopt applies the label the
+// numbered entry would have. **In place, not released and re-claimed**: a release would free the tree
+// for a moment another session could claim it in, and the record's owner and stop marks stay as written.
+
+const ADOPTED = 'adopted'
+// The tree holds no record, so there is nothing to hand over.
+const NO_RECORD = 'none'
+const FOREIGN = 'foreign'
+const UNREADABLE = 'unreadable'
+
+type AdoptResult = typeof ADOPTED | typeof FOREIGN | typeof NO_RECORD | typeof UNREADABLE
+
+// The record re-keyed: the unnumbered run's own, or one already naming `<N>` — a repeated adopt is
+// the same hand-over, so it answers alike. Another issue's record is never touched.
+function rekey(target: string, issue: string): AdoptResult {
+	const read = run_hold.read_hold(target)
+
+	if (read.kind === 'unreadable') return UNREADABLE
+
+	const hold = run_halfrun_resume.hold_of(read)
+
+	if (hold === undefined) return NO_RECORD
+
+	if (hold.issue !== run_hold.UNNUMBERED_ISSUE && hold.issue !== issue) return FOREIGN
+
+	stamp_file.write_stamp(target, { ...hold, issue })
+
+	return ADOPTED
+}
+
+function no_record_message(issue: string): string {
+	return `run:hold --adopt: this tree holds no record to adopt — claim it with \`pnpm josh run:hold ${issue}\`.`
+}
+
+// Not the claim race's message: that one advises `--force`, which here would free another run's tree.
+function foreign_message(issue: string): string {
+	return `run:hold --adopt: this tree is held for another issue, so it is not handed to issue ${issue}; \`--adopt\` only re-keys a \`new\` run's unnumbered record.`
+}
+
+async function adopt(target: string, issue: string): Promise<AdoptResult> {
+	const result = rekey(target, issue)
+
+	if (result === ADOPTED) await run_label.mark(issue)
+
+	return result
+}
+
+const run_hold_adopt = {
+	ADOPTED,
+	NO_RECORD,
+	UNREADABLE,
+	adopt,
+	foreign_message,
+	no_record_message,
+}
+
+export type { AdoptResult }
+export { run_hold_adopt }

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

@@ -1,5 +1,3 @@
-#!/usr/bin/env tsx
-import { fileURLToPath } from 'node:url'
 import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { run_cli_fault } from '#scripts/run/run-cli-fault'
 import { run_halfrun_resume } from '#scripts/run/run-halfrun-resume'
@@ -7,7 +5,10 @@ import { run_label } from '#scripts/run/run-label'
 import { run_preflight, type PreflightDecision } from '#scripts/run/run-preflight'
 import { run_prrun_resume } from '#scripts/run/run-prrun-resume'
 import { run_tidy_cli } from '#scripts/run/tidy/run-tidy-cli'
+import { test_e2e_stamp } from '#scripts/test/test-e2e-stamp'
 import { run_hold, type HoldRead, type RunHold } from './run-hold'
+import { run_hold_adopt } from './run-hold-adopt'
+import { run_stop_notify } from './run-stop-notify'
 
 // `josh run:hold [<N>]` and `josh run:release [<N> | --force]` — the working-tree guard the typed
 // entry points ask before they start.
@@ -37,7 +38,6 @@ import { run_hold, type HoldRead, type RunHold } from './run-hold'
 
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
-const ARGV_OFFSET = 2
 const RELEASE_FLAG = '--release'
 // What removes a record this run did not write. **Deliberate friction**: every release names the run
 // it belongs to, and the one act that cannot — clearing a record somebody else left behind — is
@@ -49,10 +49,14 @@ const FULLRUN_FLAG = '--fullrun'
 const HALFRUN_STOP_FLAG = '--halfrun-stop'
 // A `prrun`'s stop before merge: its record keeps the commit it stopped on.
 const PRRUN_STOP_FLAG = '--prrun-stop'
+// A `needs-human-review` stop: marked as a `halfrun` stop is, with its own confirmation.
+const HUMAN_REVIEW_STOP_FLAG = '--human-review-stop'
+// A `new` run's hand-over of its unnumbered record to the Issue it filed (`run-hold-adopt.ts`).
+const ADOPT_FLAG = '--adopt'
 // The most a claim reads: the issue number and the one flag after it.
 const MAX_CLAIM_ARGUMENTS = 2
 const USAGE =
-	'Usage: josh run:hold [<issue-number> [--fullrun | --halfrun-stop | --prrun-stop]] | josh run:release [<issue-number> | --force]'
+	'Usage: josh run:hold [<issue-number> [--fullrun | --halfrun-stop | --human-review-stop | --prrun-stop]] | josh run:hold --adopt <issue-number> | josh run:release [<issue-number> | --force]'
 
 const COMMAND = 'run:hold'
 
@@ -64,10 +68,16 @@ const NONE_VERDICT = 'none'
 // The record is another run's, so nothing was removed. **It is not `none`**: a release that did not
 // happen must never read to a script as a tree it has just freed.
 const HELD_VERDICT = 'held'
+// A stop before commit asked on a tree `josh test:e2e` has not answered green on: nothing was marked.
+const E2E_OWED_VERDICT = 'e2e-owed'
 
 const FORCE_RELEASE_KIND = 'force-release'
 const HALFRUN_STOP_KIND = 'halfrun-stop'
+const HUMAN_REVIEW_STOP_KIND = 'human-review-stop'
 const PRRUN_STOP_KIND = 'prrun-stop'
+const ADOPT_KIND = 'adopt'
+
+type StopKind = typeof HALFRUN_STOP_KIND | typeof HUMAN_REVIEW_STOP_KIND | typeof PRRUN_STOP_KIND
 
 interface ClaimRequest {
 	kind: 'claim'
@@ -76,18 +86,25 @@ interface ClaimRequest {
 }
 
 interface StopRequest {
-	kind: typeof HALFRUN_STOP_KIND | typeof PRRUN_STOP_KIND
+	kind: StopKind
 	issue: string
 }
 
 type HoldRequest =
 	| ClaimRequest
 	| StopRequest
+	| { kind: typeof ADOPT_KIND; issue: string }
 	| { kind: 'release'; claimant: string }
 	| { kind: typeof FORCE_RELEASE_KIND }
 
+const STOP_KINDS: ReadonlySet<string> = new Set([
+	HALFRUN_STOP_KIND,
+	HUMAN_REVIEW_STOP_KIND,
+	PRRUN_STOP_KIND,
+])
+
 function is_stop_request(request: HoldRequest): request is StopRequest {
-	return request.kind === HALFRUN_STOP_KIND || request.kind === PRRUN_STOP_KIND
+	return STOP_KINDS.has(request.kind)
 }
 
 const FORCE_RELEASE_REQUEST: HoldRequest = { kind: FORCE_RELEASE_KIND }
@@ -96,14 +113,14 @@ function release_request(claimant: string): HoldRequest {
 	return { kind: 'release', claimant }
 }
 
-const STOP_KIND_BY_FLAG: ReadonlyMap<string, typeof HALFRUN_STOP_KIND | typeof PRRUN_STOP_KIND> =
-	new Map([
-		[HALFRUN_STOP_FLAG, HALFRUN_STOP_KIND],
-		[PRRUN_STOP_FLAG, PRRUN_STOP_KIND],
-	])
+const STOP_KIND_BY_FLAG: ReadonlyMap<string, StopKind> = new Map([
+	[HALFRUN_STOP_FLAG, HALFRUN_STOP_KIND],
+	[HUMAN_REVIEW_STOP_FLAG, HUMAN_REVIEW_STOP_KIND],
+	[PRRUN_STOP_FLAG, PRRUN_STOP_KIND],
+])
 
-// The flag after a numbered claim: absent, `--fullrun`, `--halfrun-stop` or `--prrun-stop`. Anything
-// else is a usage error.
+// The flag after a numbered claim: absent, `--fullrun`, `--halfrun-stop`, `--human-review-stop` or
+// `--prrun-stop`. Anything else is a usage error.
 function numbered_claim(issue: string, flag: string | undefined): HoldRequest | undefined {
 	if (flag === undefined) return { kind: 'claim', issue }
 
@@ -142,9 +159,21 @@ function parse_release(argv: ReadonlyArray<string>): HoldRequest | undefined {
 	return argv.length > 1 ? undefined : parse_release_argument(first)
 }
 
+function parse_adopt(argv: ReadonlyArray<string>): HoldRequest | undefined {
+	const [issue] = argv
+
+	if (issue === undefined || argv.length > 1) return undefined
+
+	return issue_number_shape.ISSUE_NUMBER_PATTERN.test(issue)
+		? { kind: ADOPT_KIND, issue }
+		: undefined
+}
+
 function parse_request(argv: ReadonlyArray<string>): HoldRequest | undefined {
 	if (argv[0] === RELEASE_FLAG) return parse_release(argv.slice(1))
 
+	if (argv[0] === ADOPT_FLAG) return parse_adopt(argv.slice(1))
+
 	return parse_claim(argv)
 }
 
@@ -339,25 +368,73 @@ function report_usage(): number {
 	return FAILURE_EXIT_CODE
 }
 
+const SEND_BY_KIND: Readonly<Record<StopKind, (target: string, issue: string) => Promise<void>>> = {
+	[HALFRUN_STOP_KIND]: run_stop_notify.send_halfrun,
+	[HUMAN_REVIEW_STOP_KIND]: run_stop_notify.send_human_review,
+	[PRRUN_STOP_KIND]: run_stop_notify.send_prrun,
+}
+
 // **A `halfrun` stop marks its own record** — the positive "this run has ended over its verified diff"
-// that `run:entry` adopts on `fullrun #N`. Another run's record is left alone. A `prrun` stop marks
-// its record the same way, with the commit it stopped on.
+// that `run:entry` adopts on `fullrun #N`. Another run's record is left alone. A `needs-human-review`
+// stop is the same mark, since its resume is `halfrun`'s. A `prrun` stop marks its record the same
+// way, with the commit it stopped on. **A marked stop then sends its own `confirmation`**
+// (`run-stop-notify.ts`), after the mark, since the mark rewrites the record its send is stamped on.
+async function marked_stop(target: string, request: StopRequest): Promise<number> {
+	await SEND_BY_KIND[request.kind](target, request.issue)
+
+	return report_hold()
+}
+
+// **A stop before commit has no CI E2E job behind it**, so it is refused until `josh test:e2e` has
+// answered green on this exact tree (`test-e2e-stamp.ts`). A `prrun` stop has a pull request, and CI's.
+async function e2e_refusal(request: StopRequest): Promise<number | undefined> {
+	if (request.kind === PRRUN_STOP_KIND || (await test_e2e_stamp.is_current_tree())) return undefined
+
+	return report(
+		'run:hold: `pnpm josh test:e2e` has not answered green on this tree — run it, then mark the stop again.',
+		E2E_OWED_VERDICT,
+		FAILURE_EXIT_CODE,
+	)
+}
+
 async function mark_stop(target: string, request: StopRequest): Promise<number> {
+	const refusal = await e2e_refusal(request)
+
+	if (refusal !== undefined) return refusal
+
 	const mark =
 		request.kind === PRRUN_STOP_KIND
 			? await run_prrun_resume.mark_stop_at(target, request.issue)
 			: run_halfrun_resume.mark_stop_at(target, request.issue)
 
-	if (mark === run_halfrun_resume.MARKED) return report_hold()
+	if (mark === run_halfrun_resume.MARKED) return await marked_stop(target, request)
 
 	if (mark === run_halfrun_resume.UNREADABLE) return report_unreadable_record()
 
 	return report_busy(run_hold.race_message(run_hold.read_hold(target), target))
 }
 
+// The re-keyed record answers `hold`; no record answers `none` and another issue's `busy`, each a
+// failure, since the run asking holds nothing it can stop on.
+async function adopt(target: string, issue: string): Promise<number> {
+	const result = await run_hold_adopt.adopt(target, issue)
+
+	if (result === run_hold_adopt.ADOPTED) return report_hold()
+
+	if (result === run_hold_adopt.UNREADABLE) return report_unreadable_record()
+
+	if (result === run_hold_adopt.NO_RECORD) {
+		return report(run_hold_adopt.no_record_message(issue), NONE_VERDICT, FAILURE_EXIT_CODE)
+	}
+
+	return report(run_hold_adopt.foreign_message(issue), BUSY_VERDICT, FAILURE_EXIT_CODE)
+}
+
 async function dispatch(request: HoldRequest, target: string, is_linked: boolean): Promise<number> {
 	if (request.kind === 'claim') return await claim(target, request, is_linked)
 
+	if (request.kind === ADOPT_KIND) return await adopt(target, request.issue)
+
 	if (is_stop_request(request)) return await mark_stop(target, request)
 
 	if (request.kind === FORCE_RELEASE_KIND) return force_release(target)
@@ -392,10 +469,6 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 	}
 }
 
-async function main(argv: ReadonlyArray<string>): Promise<void> {
-	process.exitCode = await run(argv)
-}
-
 const run_hold_cli = {
 	BUSY_VERDICT,
 	HELD_VERDICT,
@@ -408,6 +481,4 @@ const run_hold_cli = {
 	run,
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
-
 export { run_hold_cli }

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

@@ -0,0 +1,12 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { run_hold_cli } from './run-hold-cli'
+
+// The `josh run:hold` and `josh run:release` entry, kept apart from `run-hold-cli.ts` because other
+// modules import that one: a bundle is one file, so a main guard there would fire for every command
+// that carries it (joshuafolkken/kit#4186).
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const ARGV_OFFSET = 2
+
+	process.exitCode = await run_hold_cli.run(process.argv.slice(ARGV_OFFSET))
+}

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

@@ -0,0 +1,37 @@
+import { lane_child_marker } from '#scripts/lane/lane-child-marker'
+import { run_hold, type RunHold, type SessionOwner } from './run-hold'
+import { run_hold_session } from './run-hold-session'
+
+// Whether this session is one of a run's own (joshuafolkken/kit#4099): a lane child, or the session
+// holding the run's hold on this working tree. The run's event stream is the repository's, so a
+// session outside the run — a question answered beside a `backlogrun` — writes to it too, and what it
+// files is not the run's.
+//
+// **Unknown is outside.** Unlike the `Stop` hook's question (`run-hold-session.ts`), a hold or a session
+// with no owner recorded is not this session's: counting another session's filing as the run's is the
+// failure this answers.
+
+function is_owned(hold: RunHold, owner: SessionOwner): boolean {
+	if (hold.owner_pid === undefined || owner.owner_pid === undefined) return false
+
+	return run_hold_session.is_session_hold(hold, owner)
+}
+
+async function is_hold_owner(owner: SessionOwner): Promise<boolean> {
+	const directory = await run_hold.worktree_directory()
+	if (directory === undefined) return false
+
+	const read = run_hold.read_hold(run_hold.hold_path(directory))
+
+	return read.kind === 'held' && is_owned(read.hold, owner)
+}
+
+async function is_run_member(owner: SessionOwner = run_hold.session_owner()): Promise<boolean> {
+	if (lane_child_marker.marked_issue() !== undefined) return true
+
+	return await is_hold_owner(owner)
+}
+
+const run_hold_member = { is_run_member }
+
+export { run_hold_member }

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

@@ -0,0 +1,46 @@
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { run_halfrun_resume } from '#scripts/run/run-halfrun-resume'
+import { run_hold, type RunHold, type SessionOwner } from './run-hold'
+
+// What the `Stop` hook asks of a hold beyond "is one in place" (joshuafolkken/kit#3961): whether it is
+// this session's own run's, and whether its pause was already announced.
+//
+// **Another run's hold is not this session's pause.** A `kickoff`, or a question answered while a
+// `backlogrun` parent holds the same tree, stops in a session that holds nothing — announcing that stop
+// as the held run's "confirmation required" reports a decision nobody is waiting on.
+//
+// **Unknown is this session's own.** A record written outside an agent session, or a hook that cannot
+// read its own session, keeps the behavior the hold had before ownership was recorded: a missed notify
+// costs a person a silent pause, a wrong one only a needless Telegram.
+
+function is_same_start(recorded: string | undefined, own: string | undefined): boolean {
+	return recorded === undefined || own === undefined || recorded === own
+}
+
+function is_session_hold(hold: RunHold, owner: SessionOwner = run_hold.session_owner()): boolean {
+	if (hold.owner_pid === undefined || owner.owner_pid === undefined) return true
+
+	return hold.owner_pid === owner.owner_pid && is_same_start(hold.owner_start, owner.owner_start)
+}
+
+// **A pause is announced once, and a person's prompt ends it.** The hook's own send is recorded on the
+// hold, so a later stop of the same pause — a background notice that woke the session — finds it; a send before `pause_start` belongs to an earlier pause. An unknown start
+// announces again: a needless Telegram costs less than a silent wait.
+function is_notified_since(hold: RunHold, pause_start: string | undefined): boolean {
+	if (pause_start === undefined || hold.notified_at === undefined) return false
+
+	return Date.parse(hold.notified_at) >= Date.parse(pause_start)
+}
+
+// Stamps the send on the record in place; a tree no longer held has nothing to stamp. A stale record is
+// stamped too: the hook reads it as the hold (`hold_of`), so a run past the expiry age still finds its send.
+function mark_notified(target: string, now: Date = new Date()): void {
+	const hold = run_halfrun_resume.hold_of(run_hold.read_hold(target, now))
+	if (hold === undefined) return
+
+	stamp_file.write_stamp(target, { ...hold, notified_at: now.toISOString() })
+}
+
+const run_hold_session = { is_notified_since, is_session_hold, mark_notified }
+
+export { run_hold_session }

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

@@ -65,6 +65,10 @@ interface RunHold {
 	// fields, or by a claim made outside an agent session.
 	owner_pid?: number | undefined
 	owner_start?: string | undefined
+	// When the `Stop` hook last sent this run's `confirmation` Telegram — its own send leaves no command
+	// on the transcript, so the record is what keeps one pause from being announced twice
+	// (`run-hold-session.ts`).
+	notified_at?: string | undefined
 }
 
 type HoldRead =
@@ -107,6 +111,7 @@ const run_hold_schema = z.object({
 	prrun_stop_head: z.string().optional(),
 	owner_pid: z.number().optional(),
 	owner_start: z.string().optional(),
+	notified_at: z.string().optional(),
 })
 
 // `undefined` for anything that is not a well-formed record, so the caller decides what a broken one
@@ -342,6 +347,7 @@ const run_hold = {
 	race_message,
 	read_hold,
 	release_hold,
+	session_owner,
 	stale_message,
 	uncommitted_message,
 	unknown_message,
@@ -350,5 +356,5 @@ const run_hold = {
 	write_hold,
 }
 
-export type { HoldRead, RunHold, StopMarkFields }
+export type { HoldRead, RunHold, SessionOwner, StopMarkFields }
 export { run_hold }

package/scripts/run/hold/run-stop-notify.ts

@@ -0,0 +1,183 @@
+import { git_gh_issue_read } from '#scripts/gh/git-gh-issue-read'
+import { git_gh_pr_read } from '#scripts/gh/git-gh-pr-read'
+import { git_gh_repo } from '#scripts/gh/git-gh-repo'
+import { git_command } from '#scripts/git/git-command'
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { stdout_on_stderr } from '#scripts/lib/stdout-on-stderr'
+import { telegram_test } from '#scripts/notify/telegram-test'
+import type { CliValues } from '#scripts/notify/telegram-test-logic'
+import { run_stage } from '#scripts/run/run-stage'
+import { run_hold_session } from './run-hold-session'
+
+// The `confirmation` a `halfrun`, `needs-human-review` or `prrun` stop sends from `josh run:hold
+// --halfrun-stop` / `--human-review-stop` / `--prrun-stop` (joshuafolkken/kit#4135, #4156): every line is fixed once the Issue, its title and the pull
+// request are known, so it is composed here rather than copied from prose. The send goes through
+// `josh notify`'s own call and is stamped on the hold, so the `Stop` hook's own confirmation
+// (`stop-actions.ts`) finds the pause announced and does not send it again.
+//
+// **A failed send does not fail the stop**: the mark is written, and an unstamped hold is exactly what
+// lets the `Stop` hook send the confirmation in its place.
+
+const TITLE_PLACEHOLDER = '<title>'
+const PR_PLACEHOLDER = '<pr-url>'
+const HALFRUN = 'halfrun'
+const PRRUN = 'prrun'
+// Single quotes expand nothing, so a title stays one argument whatever it carries; its own `'` closes
+// the quote, emits an escaped one and reopens.
+const QUOTE = "'"
+
+interface StopFacts {
+	issue: string
+	title: string | undefined
+	issue_url: string | undefined
+	pr_url?: string | undefined
+}
+
+interface Composed {
+	values: CliValues
+	title: string | undefined
+}
+
+function single_quoted(text: string): string {
+	return QUOTE + text.replaceAll(QUOTE, String.raw`'\''`) + QUOTE
+}
+
+// Plain, not linked: every line is a command a person copies out of the Telegram.
+function reference_of(facts: StopFacts): string {
+	return issue_cite.plain(facts.issue)
+}
+
+function commit_title(facts: StopFacts): string {
+	return single_quoted(`${facts.title ?? TITLE_PLACEHOLDER} ${reference_of(facts)}`)
+}
+
+function with_urls(values: CliValues, facts: StopFacts): CliValues {
+	const with_issue =
+		facts.issue_url === undefined ? values : { ...values, 'issue-url': facts.issue_url }
+
+	return facts.pr_url === undefined ? with_issue : { ...with_issue, 'pr-url': facts.pr_url }
+}
+
+function halfrun_values(facts: StopFacts): CliValues {
+	const title = commit_title(facts)
+	const body = [
+		'halfrun ready for manual verification',
+		run_stage.next_line(HALFRUN, facts.issue),
+		`Without an agent: pnpm josh git -y ${title} && pnpm josh followup ${title}`,
+	].join('\n')
+	const values: CliValues = {
+		'task-type': 'confirmation',
+		body,
+		recommended: `Verify by hand, then prrun ${reference_of(facts)}`,
+		alternative: [`fullrun ${reference_of(facts)}`],
+	}
+
+	return with_urls(values, facts)
+}
+
+// A `needs-human-review` stop resumes as `halfrun`'s does, so its next line is `halfrun`'s; the lane
+// directory is named because the uncommitted work a person must look at lives only there.
+function human_review_values(facts: StopFacts, directory: string): CliValues {
+	const body = [
+		'needs-human-review: implemented and gated, stopped before the commit',
+		run_stage.next_line(HALFRUN, facts.issue),
+		`Working tree: ${directory}`,
+	].join('\n')
+	const values: CliValues = {
+		'task-type': 'confirmation',
+		body,
+		recommended: `Review the working tree, then prrun ${reference_of(facts)}`,
+		alternative: [`fullrun ${reference_of(facts)}`],
+	}
+
+	return with_urls(values, facts)
+}
+
+function prrun_values(facts: StopFacts): CliValues {
+	const body = [
+		`prrun ready to merge: ${facts.pr_url ?? PR_PLACEHOLDER}`,
+		run_stage.next_line(PRRUN, facts.issue),
+		`After a manual merge, without an agent: pnpm josh followup ${commit_title(facts)}`,
+	].join('\n')
+	const values: CliValues = {
+		'task-type': 'confirmation',
+		body,
+		recommended: `fullrun ${reference_of(facts)}`,
+		alternative: ['Merge by hand, then pnpm josh followup'],
+	}
+
+	return with_urls(values, facts)
+}
+
+async function issue_facts(issue: string): Promise<StopFacts> {
+	const slug = await git_gh_repo.repo_get_name_with_owner()
+	const title = await git_gh_issue_read.issue_get_title(issue)
+
+	return {
+		issue,
+		title,
+		issue_url: slug === undefined ? undefined : issue_cite.issue_url(slug, issue),
+	}
+}
+
+async function prrun_facts(issue: string): Promise<StopFacts> {
+	const pr_url = await git_gh_pr_read.pr_get_url(await git_command.branch())
+
+	return { ...(await issue_facts(issue)), pr_url }
+}
+
+// The title is passed with the values, so the send does not read it a second time.
+async function send_composed(target: string, compose: () => Promise<Composed>): Promise<void> {
+	const { values, title } = await compose()
+	const titled = title === undefined ? values : { ...values, 'issue-title': title }
+
+	await stdout_on_stderr.run(async () => {
+		await telegram_test.send_values(titled)
+	})
+	run_hold_session.mark_notified(target)
+}
+
+// A `gh` read that fails is a send that did not happen, never a failed stop: the mark is already written.
+async function send(target: string, compose: () => Promise<Composed>): Promise<void> {
+	try {
+		await send_composed(target, compose)
+	} catch (error) {
+		console.error(`⚠️  run:hold could not send the stop confirmation: ${String(error)}`)
+	}
+}
+
+async function send_halfrun(target: string, issue: string): Promise<void> {
+	await send(target, async () => {
+		const facts = await issue_facts(issue)
+
+		return { values: halfrun_values(facts), title: facts.title }
+	})
+}
+
+async function send_prrun(target: string, issue: string): Promise<void> {
+	await send(target, async () => {
+		const facts = await prrun_facts(issue)
+
+		return { values: prrun_values(facts), title: facts.title }
+	})
+}
+
+async function send_human_review(target: string, issue: string): Promise<void> {
+	await send(target, async () => {
+		const facts = await issue_facts(issue)
+		const directory = await git_command.repository_root()
+
+		return { values: human_review_values(facts, directory), title: facts.title }
+	})
+}
+
+const run_stop_notify = {
+	halfrun_values,
+	human_review_values,
+	prrun_values,
+	send_halfrun,
+	send_human_review,
+	send_prrun,
+}
+
+export { run_stop_notify }

package/scripts/run/launch-priority.ts

@@ -0,0 +1,32 @@
+import { setPriority } from 'node:os'
+
+// **A launched session runs below the interactive one, so a saturated machine still answers the
+// user.** Every headless session and everything it starts — gates, tests, builds — used to share the
+// interactive session's priority, and at a load of ~30 the lanes took the terminal's responsiveness
+// with them (#3947). The niceness is set on the child right after `spawn` returns: a process inherits
+// its parent's niceness at fork, and an agent CLI boots for far longer than this takes before it forks
+// anything, so every descendant inherits it. Efficiency-core confinement (`taskpolicy -b`) is not
+// used — it throttles a lane far beyond yielding to the user.
+const LANE_NICENESS = 10
+
+type SetPriority = (pid: number, priority: number) => void
+
+// **A priority that cannot be lowered starts the session as before.** A platform without the call, or
+// a child that already runs at a lower priority than this, is not a reason to fail the launch.
+function lower(pid: number | undefined, set_priority: SetPriority = setPriority): void {
+	if (pid === undefined) return
+
+	try {
+		set_priority(pid, LANE_NICENESS)
+	} catch {
+		// the session keeps the priority it was started with
+	}
+}
+
+const launch_priority = {
+	LANE_NICENESS,
+	lower,
+}
+
+export type { SetPriority }
+export { launch_priority }

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

@@ -0,0 +1,31 @@
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { telegram_notify } from '#scripts/notify/telegram-notify'
+import { run_event_stream } from '#scripts/run/event/run-event-stream'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
+
+// A returned child whose session could not authenticate (joshuafolkken/kit#4216). Nothing is counted
+// and no label is touched — the child keeps `in-progress`, so it resumes once a person runs `/login` —
+// and the run stops, since every child dispatched before that fails the same way. The stop is pushed
+// as a `confirmation`: `/login` is a person's to run, and the driver's own stop notice names no cause.
+// Script-emitted, so English.
+
+const RECOVERY =
+	'If this did not arrive, `pnpm josh run:wake --list` relays the last progress line.'
+
+async function stop(child: string): Promise<void> {
+	const cite = issue_cite.plain(child)
+	const text = `${cite} could not authenticate — run /login, then resume it`
+
+	await run_event_stream_emit.emit(run_event_stream.EVENT_KIND.OUTAGE, text)
+	await telegram_notify.confirm({
+		issue_title: 'backlogrun stopped: Claude authentication failed',
+		body: `${text}. The child stays in-progress and was neither parked nor counted as a failure.`,
+		recovery: RECOVERY,
+		recommended: `Run /login, then run backlogrun again to resume ${cite}`,
+		alternatives: ['Leave the backlog stopped until a later session'],
+	})
+}
+
+const run_merge_auth = { stop }
+
+export { run_merge_auth }