@joshuafolkken/kit 1.1514.0 → 1.1784.0

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-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/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 }