@joshuafolkken/kit 1.872.0

package/scripts/git/stash-orphans.ts

@@ -0,0 +1,91 @@
+import { run_preflight } from '#scripts/run/run-preflight'
+import type { StashEntry } from './git-stash'
+
+// Which stashes nobody is coming back for (joshuafolkken/kit#2505). A parked or paused run pushes its
+// work with a message `josh stash:pop` later targets, but an issue closed by another route leaves that
+// entry with no run to pop it — the pile #2168 sorted by hand. This reads the owning issue out of each
+// entry's subject so the closed ones, and the ones with no readable owner, can be put in front of a
+// person. **Nothing here drops a stash**: the entry may hold work nobody recovered, so the decision stays
+// with the person the report is printed for.
+
+// The three shapes a run's stash subject takes, tried in this order. An explicit `#N` in the message
+// (`backlogrun: parked #N`) names the issue outright; a message that
+// opens with `N: ` is `git_stash.work_message`'s; and a lane branch (`On N-lane: …`) names it by where
+// the work was pushed from. A subject is `On <branch>: <message>` (or `WIP on <branch>: …` without
+// `-m`), and a branch name carries no `:`, so `(?:^|: )` anchors the message start either way.
+const MESSAGE_PATTERNS: ReadonlyArray<RegExp> = [/#(?<issue>\d+)\b/u, /(?:^|: )(?<issue>\d+): /u]
+const BRANCH_PATTERN = /^(?:WIP on|On) (?<issue>\d+)-lane: /u
+// A stash pushed without `-m` lists as `WIP on <branch>: <sha> <HEAD's commit subject>` — text no run
+// wrote. This repository's commit subjects end in `#N` and merges read `Merge pull request #N`, so a
+// message pattern there would name the last merged pull request, closed by definition, as the owner of
+// live work. Only the branch can name the owner of such an entry.
+const WIP_PREFIX = 'WIP on '
+// `run:hold` stashes an earlier run's leftovers before claiming the tree for `#N`, so the `#N` in that
+// message is the run that found the work, not its owner — the entry has none, and no run pops it.
+const NO_PATTERNS: ReadonlyArray<RegExp> = []
+
+const HEADER =
+	'Stashes whose issue is closed, or whose owner cannot be read — decide for each whether to revive or discard it (none is dropped automatically):'
+const FOOTER =
+	'Revive: `pnpm josh stash:pop "<message>"` · Discard: `git stash drop <selector>` — re-read the selector first, the stack is shared by every lane.'
+const UNKNOWN_OWNER = 'owner unknown'
+const COLUMN_SEPARATOR = '  '
+const LINE_SEPARATOR = '\n'
+
+interface OrphanStash {
+	selector: string
+	subject: string
+	issue: string | undefined
+}
+
+function patterns_for(subject: string): ReadonlyArray<RegExp> {
+	if (subject.includes(run_preflight.STASH_LABEL_PREFIX)) return NO_PATTERNS
+
+	return subject.startsWith(WIP_PREFIX) ? [BRANCH_PATTERN] : [...MESSAGE_PATTERNS, BRANCH_PATTERN]
+}
+
+function issue_of(subject: string): string | undefined {
+	for (const pattern of patterns_for(subject)) {
+		const issue = pattern.exec(subject)?.groups?.['issue']
+
+		if (issue !== undefined) return issue
+	}
+
+	return undefined
+}
+
+// Each owning issue once, so a stack holding two entries for one issue reads its state once.
+function issues_of(entries: ReadonlyArray<StashEntry>): Array<string> {
+	const issues = entries.map((entry) => issue_of(entry.subject))
+
+	return [...new Set(issues.filter((issue): issue is string => issue !== undefined))]
+}
+
+// An entry is reported when its issue is in `closed`, or when it names no issue at all — an entry with
+// no owner is exactly the one no run will ever pop. An open issue's entry is still some run's to resume.
+function orphans(
+	entries: ReadonlyArray<StashEntry>,
+	closed: ReadonlySet<string>,
+): Array<OrphanStash> {
+	return entries
+		.map((entry) => ({ ...entry, issue: issue_of(entry.subject) }))
+		.filter((entry) => entry.issue === undefined || closed.has(entry.issue))
+}
+
+function format_line(orphan: OrphanStash): string {
+	const owner = orphan.issue === undefined ? UNKNOWN_OWNER : `#${orphan.issue} closed`
+
+	return `  ${[orphan.selector, owner, orphan.subject].join(COLUMN_SEPARATOR)}`
+}
+
+// `undefined` when there is nothing to report, so a clean stack prints nothing at all.
+function format_report(found: ReadonlyArray<OrphanStash>): string | undefined {
+	if (found.length === 0) return undefined
+
+	return [HEADER, ...found.map((orphan) => format_line(orphan)), FOOTER].join(LINE_SEPARATOR)
+}
+
+const stash_orphans = { format_report, issue_of, issues_of, orphans }
+
+export type { OrphanStash }
+export { stash_orphans }

package/scripts/git/stash-pop-args.ts

@@ -0,0 +1,59 @@
+import { parseArgs } from 'node:util'
+
+// `josh stash:pop` turns its `argv` into a single request: the message of the stash to pop. Parsing
+// lives here, acting on the stack lives in `stash-pop-cli.ts`, and a malformed command line is
+// `undefined` rather than a guessed intent — a pop run on a misread argument would take the wrong
+// entry off a stack shared by every lane (joshuafolkken/kit#2050).
+
+const USAGE = 'Usage: josh stash:pop "<message>" [--dir <path>]'
+
+// `--dir` points the pop at a lane's work tree; without it the pop lands in the current checkout.
+const OPTIONS = { dir: { type: 'string' } } as const
+
+interface ParsedValues {
+	values: { dir?: string }
+	positionals: ReadonlyArray<string>
+}
+
+interface Request {
+	message: string
+	dir: string | undefined
+}
+
+function read_arguments(argv: ReadonlyArray<string>): ParsedValues | undefined {
+	try {
+		const parsed = parseArgs({
+			args: [...argv],
+			options: OPTIONS,
+			strict: true,
+			allowPositionals: true,
+		})
+
+		return { values: parsed.values, positionals: parsed.positionals }
+	} catch {
+		return undefined
+	}
+}
+
+// The message is the sole positional and must be a non-empty string: an empty message matches every
+// stash pushed without a message, which is exactly the ambiguity this command exists to refuse.
+function message_of(positionals: ReadonlyArray<string>): string | undefined {
+	if (positionals.length !== 1) return undefined
+
+	const [message] = positionals
+
+	return message === '' ? undefined : message
+}
+
+function to_request(parsed: ParsedValues): Request | undefined {
+	const message = message_of(parsed.positionals)
+
+	if (message === undefined) return undefined
+
+	return { message, dir: parsed.values.dir }
+}
+
+const stash_pop_args = { USAGE, message_of, read_arguments, to_request }
+
+export type { Request }
+export { stash_pop_args }

package/scripts/git/stash-pop-cli.ts

@@ -0,0 +1,105 @@
+import { fileURLToPath } from 'node:url'
+import { git_stash } from './git-stash'
+import { stash_pop_args, type Request } from './stash-pop-args'
+
+// `josh stash:pop "<message>"` — pop the stash whose message matches, and no other
+// (joshuafolkken/kit#2050). The stash stack is shared by every working tree of the repository, so a
+// procedure that pops by position takes whatever another lane last pushed. This resolves the
+// selector from the message and pops that entry alone; no match and more than one match are both
+// refusals rather than a guess at which was meant.
+
+const POPPED_VERDICT = 'popped'
+const CONFLICTED_VERDICT = 'conflicted'
+const NO_MATCH_VERDICT = 'no-match'
+const AMBIGUOUS_VERDICT = 'ambiguous'
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const ARGV_OFFSET = 2
+
+function report(verdict: string, detail: string, code: number): number {
+	console.info(verdict)
+	console.error(detail)
+
+	return code
+}
+
+function refuse(): number {
+	console.error(stash_pop_args.USAGE)
+
+	return FAILURE_EXIT_CODE
+}
+
+// A pop that leaves unmerged paths applied the stash and only needs the conflicts resolved, so it is
+// reported `conflicted` at exit 0 rather than raised as an unknown failure (joshuafolkken/kit#2050);
+// any other pop error is re-thrown for `run` to report. `has_conflict` reads the tree the pop wrote.
+async function pop_selected(selector: string, directory: string | undefined): Promise<number> {
+	try {
+		await git_stash.pop(selector, directory)
+	} catch (error) {
+		if (await git_stash.has_conflict(directory)) {
+			const detail = `Popped ${selector} with conflicts — resolve them.`
+
+			return report(CONFLICTED_VERDICT, detail, SUCCESS_EXIT_CODE)
+		}
+
+		throw error
+	}
+
+	return report(POPPED_VERDICT, `Popped ${selector}.`, SUCCESS_EXIT_CODE)
+}
+
+async function answer(request: Request): Promise<number> {
+	const selection = git_stash.select(await git_stash.list(request.dir), request.message)
+
+	if (selection.kind === 'none') {
+		return report(NO_MATCH_VERDICT, `No stash matches "${request.message}".`, FAILURE_EXIT_CODE)
+	}
+
+	if (selection.kind === 'ambiguous') {
+		const detail = `More than one stash matches "${request.message}": ${selection.selectors.join(', ')}.`
+
+		return report(AMBIGUOUS_VERDICT, detail, FAILURE_EXIT_CODE)
+	}
+
+	return await pop_selected(selection.selector, request.dir)
+}
+
+function report_unknown(error: unknown): number {
+	console.error(error instanceof Error ? error.message : String(error))
+
+	return FAILURE_EXIT_CODE
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const parsed = stash_pop_args.read_arguments(argv)
+
+	if (parsed === undefined) return refuse()
+
+	const request = stash_pop_args.to_request(parsed)
+
+	if (request === undefined) return refuse()
+
+	try {
+		return await answer(request)
+	} catch (error) {
+		return report_unknown(error)
+	}
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const stash_pop_cli = {
+	AMBIGUOUS_VERDICT,
+	CONFLICTED_VERDICT,
+	NO_MATCH_VERDICT,
+	POPPED_VERDICT,
+	main,
+	run,
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { stash_pop_cli }

package/scripts/git/telegram-notify.ts

@@ -0,0 +1,404 @@
+import { gh_spawn } from '#scripts/gh/gh-spawn'
+import { z } from 'zod'
+
+const TELEGRAM_API_BASE = 'https://api.telegram.org'
+
+const telegram_environment_schema = z.object({
+	telegram_bot_token: z.string().min(1, { message: 'TELEGRAM_BOT_TOKEN is required' }),
+	telegram_chat_id: z.string().min(1, { message: 'TELEGRAM_CHAT_ID is required' }),
+})
+
+// **`warning` is not `failure`** (joshuafolkken/kit#1628). It names a run that finished and merged,
+// alongside something that did not work — a post-merge cleanup step that could not complete is one.
+// Sending `failure` (❌) there would say the merge failed, which is false and is
+// the more expensive lie of the two; sending `completion` (✅) twice says nothing went wrong, which
+// is the silence this type exists to end.
+// **`stalled` is not `warning`** (joshuafolkken/kit#2359). `warning` names a run that *finished* and
+// merged alongside something that did not work; a stall is the opposite — the run is alive and has not
+// finished, it has simply stopped advancing while ready work waits for a free lane. The ⏳ icon says
+// exactly that: not done, not broken, just not moving.
+// **`stranded` is not `stalled`** (joshuafolkken/kit#2375). A stall is a *live* run that is not
+// dispatching; a strand is the step before it — the run's own driver is gone. The session that cut the
+// budget handed it off and died, no successor claimed it, and no supervisor is watching, so nothing can
+// take the next step at all. The 🚨 icon says a run needs a hand, not that ready work is merely waiting.
+type TelegramTaskType =
+	| 'planning'
+	| 'completion'
+	| 'failure'
+	| 'warning'
+	| 'kickoff_retry'
+	| 'confirmation'
+	| 'stalled'
+	| 'stranded'
+
+interface TelegramSendInput {
+	task_type: TelegramTaskType
+	repo_name: string | undefined
+	issue_title: string | undefined
+	body: string | undefined
+	issue_url: string | undefined
+	pr_url: string | undefined
+}
+
+interface TelegramConfig {
+	bot_token: string
+	chat_id: string
+}
+
+interface TaskDefinition {
+	icon: string
+	label: string
+}
+
+const TASK_DEFINITIONS: Record<TelegramTaskType, TaskDefinition> = {
+	planning: { icon: '📋', label: 'Planning' },
+	completion: { icon: '✅', label: 'Completion' },
+	failure: { icon: '❌', label: 'Failure' },
+	warning: { icon: '⚠️', label: 'Completed with a warning' },
+	kickoff_retry: { icon: '🔄', label: 'Kickoff retry' },
+	confirmation: { icon: '⏸️', label: 'Confirmation required' },
+	stalled: { icon: '⏳', label: 'Ready work is sitting undispatched' },
+	stranded: { icon: '🚨', label: 'Run stranded — nobody is driving it' },
+}
+
+const NOT_CONFIGURED_PREFIX = 'Telegram is not configured'
+const SEND_FAILED_PREFIX = 'Telegram notification failed'
+const REDACTED = '<redacted>'
+const UNKNOWN_ERROR_TEXT = 'unknown error'
+
+function parse_environment_string(value: string | undefined): string {
+	return value?.trim() ?? ''
+}
+
+// Not `git_gh_helpers.get_error_message_with_stderr`, which the two nearest callers use: that one
+// appends the `stderr` an execa-shaped error carries, and nothing in this module runs a subprocess —
+// so it would pull a subprocess concern into an HTTP one and degrade to exactly this line anyway.
+// **The `cause` is read, not only the message.** A `fetch` rejection's own message is the bare string
+// `fetch failed`; what says whether this was DNS, a refused connection or a timeout lives one level
+// down. Reporting the top line alone would exit non-zero with nothing a reader can act on, which is
+// half of what joshuafolkken/kit#1564 set out to fix. Redaction runs over the joined text, so the
+// deeper line is covered exactly as the top one is.
+function join_cause(error: Error): string {
+	const { cause } = error
+
+	if (!(cause instanceof Error) || cause.message.length === 0) return error.message
+
+	return `${error.message}: ${cause.message}`
+}
+
+// A non-`Error` throw is stated rather than stringified: `String({})` is `[object Object]`, which
+// tells a reader nothing and is what `typescript:S6551` flags.
+function describe_non_error(error: unknown): string {
+	return typeof error === 'string' ? error : UNKNOWN_ERROR_TEXT
+}
+
+function describe_error(error: unknown): string {
+	if (error instanceof Error) return join_cause(error)
+
+	return describe_non_error(error)
+}
+
+// **The message alone, for an error this module built itself.** What `send` throws already carries
+// the joined cause inside its own message, and its `cause` is a redacted copy of that same text — so
+// walking the chain again here printed the whole reason twice on one line.
+function describe_symptom(error: unknown): string {
+	return error instanceof Error ? error.message : describe_non_error(error)
+}
+
+// The request URL carries the bot token in its own path, so an error raised anywhere near the
+// request can carry a credential into a log. Both values are taken out of the text before it leaves
+// this module, so no caller has to remember to do it (joshuafolkken/kit#1564).
+function redact_credentials(text: string, config: TelegramConfig): string {
+	return text.split(config.bot_token).join(REDACTED).split(config.chat_id).join(REDACTED)
+}
+
+// **Missing credentials are a failure, not a skip** (joshuafolkken/kit#1564). This used to warn and
+// return `undefined`, and `send` then returned quietly — so a run with no credentials was
+// indistinguishable from one whose notification arrived. Until this Issue the mandatory
+// `--env-file=.env` flag on `josh notify` and `josh followup` made a machine without that file die
+// before node started, which was loud by accident; with the flag relaxed to the optional form, this
+// is where the noise has to come from instead.
+//
+// The message names the variables and never their values — the schema's own messages are the
+// variable names, so nothing read out of the environment reaches it.
+function load_config(): TelegramConfig {
+	const result = telegram_environment_schema.safeParse({
+		telegram_bot_token: parse_environment_string(process.env['TELEGRAM_BOT_TOKEN']),
+		telegram_chat_id: parse_environment_string(process.env['TELEGRAM_CHAT_ID']),
+	})
+
+	if (!result.success) {
+		const error_list = result.error.issues.map((issue) => issue.message).join(', ')
+
+		throw new Error(`${NOT_CONFIGURED_PREFIX}: ${error_list}`)
+	}
+
+	return { bot_token: result.data.telegram_bot_token, chat_id: result.data.telegram_chat_id }
+}
+
+function build_header(task_type: TelegramTaskType, repo_name: string | undefined): string {
+	const { icon, label } = TASK_DEFINITIONS[task_type]
+	if (repo_name === undefined || repo_name.length === 0) return `${icon} ${label}`
+
+	return `${icon} ${repo_name}: ${label}`
+}
+
+function push_if_present(target: Array<string>, value: string | undefined): void {
+	if (value !== undefined && value.length > 0) target.push(value)
+}
+
+function build_title_block(input: TelegramSendInput): string {
+	const lines: Array<string> = [build_header(input.task_type, input.repo_name)]
+
+	push_if_present(lines, input.issue_title)
+
+	return lines.join('\n')
+}
+
+function append_url(parts: Array<string>, label: string, value: string | undefined): void {
+	if (value !== undefined && value.length > 0) parts.push(`${label}: ${value}`)
+}
+
+function build_url_parts(input: TelegramSendInput): Array<string> {
+	const parts: Array<string> = []
+
+	append_url(parts, 'Issue', input.issue_url)
+	append_url(parts, 'PR', input.pr_url)
+
+	return parts
+}
+
+function build_blocks(input: TelegramSendInput): Array<string> {
+	const blocks: Array<string> = [build_title_block(input)]
+
+	push_if_present(blocks, input.body)
+	blocks.push(...build_url_parts(input))
+
+	return blocks
+}
+
+function build_text(input: TelegramSendInput): string {
+	return build_blocks(input).join('\n\n')
+}
+
+async function post_message(config: TelegramConfig, text: string): Promise<void> {
+	const url = `${TELEGRAM_API_BASE}/bot${config.bot_token}/sendMessage`
+	const response = await fetch(url, {
+		method: 'POST',
+		headers: { 'Content-Type': 'application/json' },
+		body: JSON.stringify({ chat_id: config.chat_id, text }),
+	})
+
+	if (!response.ok) {
+		throw new Error(`Telegram API error: ${String(response.status)} ${response.statusText}`)
+	}
+}
+
+// **The cause is re-wrapped rather than passed through** (joshuafolkken/kit#1564). The chain is kept,
+// because a symptom error that drops its cause loses where the failure came from — but the original
+// is the one object on this path nothing has redacted, and `git_error.handle` prints a cause's own
+// message straight to the console. Both layers therefore carry the same already-redacted text.
+function build_send_failure(error: unknown, config: TelegramConfig): Error {
+	const reason = redact_credentials(describe_error(error), config)
+
+	return new Error(`${SEND_FAILED_PREFIX}: ${reason}`, { cause: new Error(reason) })
+}
+
+// **The strict form.** A caller whose whole job is the notification has nothing left to report when
+// this fails, so it throws and `pnpm josh notify` exits non-zero. joshuafolkken/kit#1564 measured
+// the state this replaces: three notifications lost to a `504 Gateway Time-out`, each one printing a
+// warning and exiting 0, so a message that reached nobody looked exactly like one that arrived.
+//
+// The failure it throws carries a `cause`, and that cause is redacted too — see `build_send_failure`.
+async function send(input: TelegramSendInput): Promise<void> {
+	const config = load_config()
+	const text = build_text(input)
+
+	try {
+		await post_message(config, text)
+	} catch (error) {
+		throw build_send_failure(error, config)
+	}
+
+	console.info('📱 Telegram notification sent.')
+}
+
+// **The tolerant form**, for a caller whose job is something other than the notification.
+// `followup` sends the completion message on its way to the merge, and a gateway timeout at
+// Telegram is not a reason to leave a reviewed, green pull request unmerged — joshuafolkken/kit#1564
+// measured exactly that 504 with six lanes running at once. So the failure is reported and the run
+// carries on.
+//
+// **Reported under `❗` on stderr, in its own block, with the caller's own recovery line** — the bar
+// joshuafolkken/kit#1539 set for a step that failed and was not allowed to end the run. The `⚠️`
+// this used to print is what every routine notice prints, which is how the failure got buried.
+//
+// `recovery` is the caller's because only the caller knows one. It is `string | undefined` and not
+// optional for the reason `CleanupStep.recovery` is: a caller with no command that finishes the job
+// has to say so rather than leave the field off, and naming a command that would not work sends the
+// reader somewhere useless.
+//
+// **Not routed through `git_followup_cleanup`**, which is that Issue's mechanism: it guards the
+// steps a merge has already earned and says "failed after the merge" in its own wording, while this
+// send happens *before* the merge. Borrowing it would print a sentence that is not true.
+function report_send_failure(error: unknown, recovery: string | undefined): void {
+	console.error('')
+	console.error(`❗ ${describe_symptom(error)}`)
+	console.error('   Nobody was notified, and the run carried on.')
+
+	if (recovery !== undefined) console.error(`   Recovery: ${recovery}`)
+
+	console.error('')
+}
+
+async function send_or_report(
+	input: TelegramSendInput,
+	recovery: string | undefined,
+): Promise<boolean> {
+	try {
+		await send(input)
+
+		return true
+	} catch (error) {
+		report_send_failure(error, recovery)
+
+		return false
+	}
+}
+
+// Long enough that a stalled `gh` never holds a warning back, short enough that the message still
+// names the repository it is about.
+const REPO_LOOKUP_TIMEOUT_MS = 5000
+
+interface WarningInput {
+	issue_title: string
+	body: string
+	recovery: string
+}
+
+/**
+ * Warn that something an unattended run depended on did not work.
+ *
+ * **One function rather than one per caller** (joshuafolkken/kit#1749). Every warning fills in the
+ * same four fields the same way — the task type, the repository looked up under the same bound, and
+ * two urls that are never known here — so a second caller composing its own would be free to drift
+ * on the one field that is not obvious: a repository lookup with no timeout hangs the warning behind
+ * the failure it is reporting.
+ */
+async function warn(input: WarningInput): Promise<boolean> {
+	return await send_or_report(
+		{
+			task_type: 'warning',
+			repo_name: gh_spawn.get_repo_name_with_owner_within(REPO_LOOKUP_TIMEOUT_MS),
+			issue_title: input.issue_title,
+			body: input.body,
+			issue_url: undefined,
+			pr_url: undefined,
+		},
+		input.recovery,
+	)
+}
+
+interface ConfirmInput {
+	issue_title: string
+	body: string
+	recovery: string
+}
+
+/**
+ * Push the ⏸️ confirmation type — a state change an unattended run made that a person now has to act
+ * on, a `backlogrun` that stopped needing a decision being the one this was written for
+ * (joshuafolkken/kit#2136).
+ *
+ * **One function rather than one per caller, for `warn`'s reason exactly**: the repository lookup
+ * under a timeout is the field a second caller composing the four itself would drift on, and a lookup
+ * with no bound hangs the confirmation behind the very stop it is announcing. The tolerant `send_or_report`
+ * is used, not the strict `send`: the run is ending either way, so a gateway timeout at Telegram must
+ * not turn a stop into a crash — the pull path (`pnpm josh run:wake --list`) is the fallback the
+ * `recovery` line names.
+ */
+async function confirm(input: ConfirmInput): Promise<boolean> {
+	return await send_or_report(
+		{
+			task_type: 'confirmation',
+			repo_name: gh_spawn.get_repo_name_with_owner_within(REPO_LOOKUP_TIMEOUT_MS),
+			issue_title: input.issue_title,
+			body: input.body,
+			issue_url: undefined,
+			pr_url: undefined,
+		},
+		input.recovery,
+	)
+}
+
+interface StalledInput {
+	body: string
+	recovery: string
+}
+
+/**
+ * Push the ⏳ stalled type — ready backlog work with a free lane that nothing has dispatched for a while
+ * (joshuafolkken/kit#2359). Off-screen is the whole point: the state is invisible on the terminal until
+ * a person asks, so it reaches them where they are not watching.
+ *
+ * **`warn`'s shape exactly** — the repository looked up under the shared bound, the tolerant
+ * `send_or_report` so a gateway timeout at Telegram never fails the detector that is only reporting, and
+ * the caller's own `recovery` line. No `issue_title`: the header label already names what this is, and
+ * the body carries what is waiting, so a title line would only repeat the header.
+ */
+async function stalled(input: StalledInput): Promise<boolean> {
+	return await send_or_report(
+		{
+			task_type: 'stalled',
+			repo_name: gh_spawn.get_repo_name_with_owner_within(REPO_LOOKUP_TIMEOUT_MS),
+			issue_title: undefined,
+			body: input.body,
+			issue_url: undefined,
+			pr_url: undefined,
+		},
+		input.recovery,
+	)
+}
+
+interface StrandedInput {
+	body: string
+	recovery: string
+}
+
+/**
+ * Push the 🚨 stranded type — a run whose driver is gone and which nothing can advance
+ * (joshuafolkken/kit#2375). Off-screen is the whole point, as it is for `stalled`: the state is
+ * invisible on the terminal because the session that would show it has died, so the person hears about
+ * it where they are not watching, rather than by asking.
+ *
+ * **`stalled`'s shape exactly** — the repository looked up under the shared bound, the tolerant
+ * `send_or_report` so a Telegram timeout never fails the detector that is only reporting, and the
+ * caller's own `recovery` line naming the command that hands the run to a fresh supervisor. No
+ * `issue_title`: the header label already names what this is.
+ */
+async function stranded(input: StrandedInput): Promise<boolean> {
+	return await send_or_report(
+		{
+			task_type: 'stranded',
+			repo_name: gh_spawn.get_repo_name_with_owner_within(REPO_LOOKUP_TIMEOUT_MS),
+			issue_title: undefined,
+			body: input.body,
+			issue_url: undefined,
+			pr_url: undefined,
+		},
+		input.recovery,
+	)
+}
+
+const telegram_notify = {
+	REPO_LOOKUP_TIMEOUT_MS,
+	confirm,
+	send,
+	send_or_report,
+	stalled,
+	stranded,
+	warn,
+}
+
+export { telegram_notify, build_text, TASK_DEFINITIONS, telegram_environment_schema }
+export type { TelegramSendInput, TelegramTaskType }