@joshuafolkken/kit 1.1240.0 → 1.1373.0

package/scripts/lint/cspell-cached.ts

@@ -6,7 +6,7 @@ import { lane_cache_run } from '#scripts/lane/lane-cache-run'
 import { buffered_process, FAIL_EXIT_CODE } from '#scripts/lib/buffered-process'
 
 const ARGV_START = 2
-// `--no-progress` turns off cspell's per-file `N/1607 <path> cached` line (joshuafolkken/kit#2296).
+// `--no-progress` turns off cspell's per-file `N/1607 <path> cached` line.
 // Those lines ran to 1,607 of them — the whole output past the 8,000-character tool cap — so a gate
 // that failed on one unknown word buried the failure under progress and a run could read only the
 // first of several failures. The summary and the issue lines it prints are untouched; only the

package/scripts/lint/format.ts

@@ -19,8 +19,7 @@ async function run_step(args: ReadonlyArray<string>, directory: string): Promise
 
 // prettier first, deliberately: `eslint --fix` exits 1 whenever a non-autofixable error remains, so
 // putting it first would mean one unused variable anywhere in the tree stops prettier from running.
-// A basic project without Prettier or ESLint is skipped with the same reason `josh lint` prints
-// (joshuafolkken/kit#2693, joshuafolkken/kit#2606).
+// A basic project without Prettier or ESLint is skipped with the same reason `josh lint` prints.
 async function run_unless_skipped(
 	check: string,
 	reason: string | undefined,

package/scripts/lint/lint-parallel.ts

@@ -8,22 +8,35 @@ import {
 	FAIL_EXIT_CODE,
 	type BufferedProcessResult,
 } from '#scripts/lib/buffered-process'
+import { cross_file_recheck, type CrossFileRecheckOptions } from './cross-file-recheck'
 
 const PRETTIER_ARGS = ['exec', 'prettier', '--check', '.'] as const
 // This — not the `lint:eslint` map entry — is the eslint invocation `josh gate` reaches, so the
-// cache flags come from the same constant the ignore rules are asserted against
-// (joshuafolkken/kit#1256). A copy here would keep writing the old location the day that constant
+// cache flags come from the same constant the ignore rules are asserted against.
+// A copy here would keep writing the old location the day that constant
 // moves, with every test still green.
-const ESLINT_ARGS = ['exec', 'eslint', '.', ...ESLINT_CACHE_FLAGS] as const
+const WHOLE_TREE = '.'
+const ESLINT_ARGS = ['exec', 'eslint', WHOLE_TREE, ...ESLINT_CACHE_FLAGS] as const
+const WHOLE_TREE_RECHECK: CrossFileRecheckOptions = {
+	cache_file: ESLINT_CACHE_FILE,
+	patterns: [WHOLE_TREE],
+}
 
-async function run_eslint(
-	eslint_args: ReadonlyArray<string>,
-	cache_file: string,
-): Promise<BufferedProcessResult> {
-	return await lane_cache_run.run(
-		cache_file,
-		async () => await buffered_process.run_buffered_process(eslint_args),
-	)
+// What one eslint run is made of: the child's arguments, and what re-reading a cached cross-file report
+// (`cross-file-recheck.ts`) needs to ask the same question again — the cache file and the targets.
+interface EslintRun {
+	args: ReadonlyArray<string>
+	recheck: CrossFileRecheckOptions
+}
+
+// The finished report is re-read before it is returned, inside the lane's cache sharing, because
+// the re-reading uses that same cache file.
+async function run_eslint(eslint: EslintRun): Promise<BufferedProcessResult> {
+	return await lane_cache_run.run(eslint.recheck.cache_file, async () => {
+		const result = await buffered_process.run_buffered_process(eslint.args)
+
+		return await cross_file_recheck.verify(result, eslint.recheck)
+	})
 }
 
 function write_output(result: BufferedProcessResult): void {
@@ -46,13 +59,12 @@ async function run_prettier(
 
 async function run_checked_eslint(
 	directory: string,
-	eslint_args: ReadonlyArray<string>,
-	cache_file: string,
+	eslint: EslintRun,
 ): Promise<BufferedProcessResult> {
 	const reason = project_checks.eslint_skip_reason(directory)
 	if (reason !== undefined) return skipped('eslint', reason)
 
-	return await run_eslint(eslint_args, cache_file)
+	return await run_eslint(eslint)
 }
 
 function lint_exit_code(prettier: BufferedProcessResult, eslint: BufferedProcessResult): number {
@@ -63,19 +75,23 @@ function lint_exit_code(prettier: BufferedProcessResult, eslint: BufferedProcess
 
 // The two checks are run from here whether they were pointed at the whole tree or at one change's
 // files, so `josh lint:related` reaches prettier and eslint through the same buffering, the same
-// "one failure does not abort the other" reading, and the same exit code (joshuafolkken/kit#1298) —
+// "one failure does not abort the other" reading, and the same exit code —
 // and through the same basic-project skip, so a narrowed run never reaches a tool the whole-tree
-// run would have skipped (joshuafolkken/kit#2709). The skip reasons answer nothing for a full
+// run would have skipped. The skip reasons answer nothing for a full
 // project, so the one path serves both profiles.
+//
+// A narrowed run re-reads a cached cross-file report too (`cross-file-recheck.ts`): one change's
+// files can hold both the reported file and the one it reads, and fixing the second leaves the
+// first's cached report standing.
 async function run_lint_checks(
 	prettier_args: ReadonlyArray<string>,
 	eslint_args: ReadonlyArray<string>,
-	eslint_cache_file: string = ESLINT_CACHE_FILE,
+	recheck: CrossFileRecheckOptions,
 ): Promise<number> {
 	const directory = process.cwd()
 	const [prettier, eslint] = await Promise.all([
 		run_prettier(directory, prettier_args),
-		run_checked_eslint(directory, eslint_args, eslint_cache_file),
+		run_checked_eslint(directory, { args: eslint_args, recheck }),
 	])
 
 	write_output(prettier)
@@ -85,7 +101,7 @@ async function run_lint_checks(
 }
 
 async function run_lint_parallel_checks(): Promise<number> {
-	return await run_lint_checks(PRETTIER_ARGS, ESLINT_ARGS)
+	return await run_lint_checks(PRETTIER_ARGS, ESLINT_ARGS, WHOLE_TREE_RECHECK)
 }
 
 // `process.exitCode` rather than `process.exit()`: both reports are buffered and written here in

package/scripts/lint/lint-related-scope.ts

@@ -5,12 +5,14 @@ import {
 	type ScopeInputs,
 	type ScopeVocabulary,
 } from '#scripts/git/changed-file-scope'
-import { ESLINT_RELATED_CACHE_FLAGS } from '#scripts/josh/josh-command-types'
+import {
+	ESLINT_RELATED_CACHE_FILE,
+	ESLINT_RELATED_CACHE_FLAGS,
+} from '#scripts/josh/josh-command-types'
+import type { CrossFileRecheckOptions } from './cross-file-recheck'
 
-// joshuafolkken/kit#1298: `josh lint` read the whole repository on every call, and an
-// implementation loop calls it after every few edits. Measured across four runs with
-// `pnpm josh time`, that came to 47–188 seconds per run — 18% of #1292's 1,043-second
-// implementation phase, spent re-reading files the change never touched.
+// `josh lint` reads the whole repository on every call, and an implementation loop calls it after
+// every few edits — re-reading files the change never touched.
 //
 // **This narrowing is added in front of the whole check, never in place of it.** `josh gate` still
 // runs `josh lint` over everything before the commit: a formatting rule can be broken by a file the
@@ -96,17 +98,14 @@ function prettier_arguments(files: ReadonlyArray<string>): ReadonlyArray<string>
 	return [...PRETTIER_ARGS, ...files]
 }
 
-// The cache file is this command's own rather than the gate's, because the two run at the same time
-// (joshuafolkken/kit#1347). `josh gate` lints the whole tree beside the review while an
+// The cache file is this command's own rather than the gate's, because the two run at the same time.
+// `josh gate` lints the whole tree beside the review while an
 // implementation loop calls this command between edits, and each eslint run rewrites its cache file
-// whole from the copy it loaded at start-up — so on one file the run that finished last discarded
-// the other's entries, and a narrowed run finishing during a whole-tree run rolled the cache back to
-// its pre-gate state.
-//
-// **The earlier comment here claimed the opposite and was reasoning about the wrong thing.** It said
-// sharing let a narrowed run warm the gate's cache, since eslint leaves the entries a run did not
-// visit alone; that holds for pruning and says nothing about two writers. It is the same judgement
-// joshuafolkken/kit#1332 made for the edit hook, applied to the second place it was needed.
+// whole from the copy it loaded at start-up — so on one file the run that finished last would
+// discard the other's entries, and a narrowed run finishing during a whole-tree run would roll the
+// cache back to its pre-gate state. Sharing would let a narrowed run warm the gate's cache only for
+// pruning, which says nothing about two writers. It is the same judgement the edit hook's own cache
+// file makes.
 //
 // **What is narrowed is still only the target list, never the gate.** `josh gate` runs `josh lint`
 // over the whole tree before any commit; this file decides which files a repeat call reads.
@@ -114,8 +113,19 @@ function eslint_arguments(files: ReadonlyArray<string>): ReadonlyArray<string> {
 	return [...ESLINT_ARGS, ...files, ...ESLINT_RELATED_CACHE_FLAGS, ...ESLINT_SCOPED_FLAGS]
 }
 
+// What re-reading a cached cross-file report (`cross-file-recheck.ts`) needs to ask the narrowed run's question
+// again: the same targets, the same cache file, and the Node API's spelling of `--no-warn-ignored`.
+function cross_file_recheck_options(files: ReadonlyArray<string>): CrossFileRecheckOptions {
+	return {
+		cache_file: ESLINT_RELATED_CACHE_FILE,
+		patterns: files,
+		eslint_options: { warnIgnored: false },
+	}
+}
+
 const lint_related_scope = {
 	COMMAND_LABEL,
+	cross_file_recheck_options,
 	NOTHING_LINTABLE_REASON,
 	describe_scope,
 	eslint_arguments,

package/scripts/lint/lint-related.ts

@@ -4,13 +4,12 @@ import { fileURLToPath } from 'node:url'
 import { document_byte_check } from '#scripts/document/document-byte-check'
 import { scoped_green } from '#scripts/gate/scoped-green'
 import { changed_file_scope, type ChangedFileScope } from '#scripts/git/changed-file-scope'
-import { ESLINT_RELATED_CACHE_FILE } from '#scripts/josh/josh-command-types'
 import { review_stamps } from '#scripts/review/review-stamps'
 import { lint_parallel } from './lint-parallel'
 import { lint_related_scope } from './lint-related-scope'
 
-// `josh lint:related` — the lint check an implementation loop runs between edits
-// (joshuafolkken/kit#1298). The narrowing itself is `lint-related-scope.ts` over the shared
+// `josh lint:related` — the lint check an implementation loop runs between edits.
+// The narrowing itself is `lint-related-scope.ts` over the shared
 // decision in `changed-file-scope.ts`; this is the process around it — how the run reaches the same
 // two child processes `josh lint` runs.
 
@@ -37,20 +36,20 @@ async function lint_exit_code(scope: ChangedFileScope): Promise<number> {
 	return await lint_parallel.run_lint_checks(
 		lint_related_scope.prettier_arguments(scope.files),
 		lint_related_scope.eslint_arguments(scope.files),
-		ESLINT_RELATED_CACHE_FILE,
+		lint_related_scope.cross_file_recheck_options(scope.files),
 	)
 }
 
 // The byte check over the same scope the lint just ran: the resolved file list when narrowed, and
 // the whole budget when lint fell back to the whole tree — so the byte check is a superset in the
-// fallback exactly as lint is, never an empty list that would pass silently (joshuafolkken/kit#2176).
+// fallback exactly as lint is, never an empty list that would pass silently.
 function byte_check_exit_code(scope: ChangedFileScope, root: string): number {
 	if (scope.mode === 'all') return document_byte_check.check_all(root)
 
 	return document_byte_check.check_files(root, scope.files)
 }
 
-// The lint result folded together with the fast byte-ceiling check (joshuafolkken/kit#2176): the
+// The lint result folded together with the fast byte-ceiling check: the
 // same check the gate's `document-byte-budget.test.ts` runs, brought forward to this between-edits
 // path so a mandated documentation update over its ceiling surfaces in seconds. It reads no change
 // of its own — it takes the files this run already resolved, so the git contract is the lint
@@ -68,7 +67,7 @@ async function scoped_exit_code(scope: ChangedFileScope, root: string): Promise<
 // whole one, and a fallback says which of the two it was rather than looking like a narrow run
 // that found nothing.
 //
-// **A green run leaves a record of the tree it was green on** (joshuafolkken/kit#1511), so
+// **A green run leaves a record of the tree it was green on**, so
 // `josh review:brief` can tell a tree this check has read from one it has not. What the record means,
 // and the three states in which it is withheld, are `scoped-green.ts`.
 async function run_related_lint(command_arguments: ReadonlyArray<string>): Promise<number> {

package/scripts/managed-marker/index.ts

@@ -1,5 +1,5 @@
 // The public surface a downstream distribution package imports to stamp the workflows it writes.
 // Exported rather than left internal because the alternative is every distributor re-implementing
 // the header, and a second implementation that spells the token differently or stacks a duplicate
-// silently breaks the check that reads it (joshuafolkken/kit#844).
+// silently breaks the check that reads it.
 export { managed_marker_logic } from './managed-marker-logic'

package/scripts/managed-marker/managed-marker-logic.ts

@@ -4,8 +4,7 @@ import { is_workflow_destination } from '#scripts/claude/workflow-destination'
 // answer has to survive being copied on: a consumer of a consumer receives `ci.yml` from kit and
 // `dast.yml` from app-kit, and neither distributor knows what the other manages. So the answer is
 // written into the artifact rather than kept in a list beside it — every distributor stamps its own
-// output, and the auto-merge workflow reads the stamp off the very file it is asking about
-// (joshuafolkken/kit#844).
+// output, and the auto-merge workflow reads the stamp off the very file it is asking about.
 //
 // A list cannot reach that far. kit's write time is the only moment kit controls, and at that moment
 // it knows nothing of what app-kit distributes; whichever sync ran last would decide the list, and

package/scripts/notify/git-notify.ts

@@ -1,3 +1,5 @@
+import { issue_cite } from '#scripts/issue/issue-cite'
+
 type NotifyTarget = 'pr' | 'issue' | 'both'
 
 interface GitNotifyConfig {
@@ -35,14 +37,13 @@ function parse_notify_mentions(raw_mentions: string | undefined): Array<string>
 }
 
 // The `\n` escape the inline `--notify-message` form needs is expanded by `cli_body` at the point the
-// flag is read, not here (joshuafolkken/kit#1198). Expanding again would rewrite a literal backslash-n
+// flag is read, not here. Expanding again would rewrite a literal backslash-n
 // that `--notify-message-file` legitimately carries — a file already holds real newlines, so an
 // escape sequence in one is the author's text rather than a quoting workaround.
 //
-// **Trimming moved up with it, and for the same reason.** This function used to read
-// `raw.trim().replaceAll(…)` — trim first, expand second. Keeping the trim here after the expansion
-// had moved reversed that order, so `--notify-message "…\n"` lost the newline its own escape had just
-// produced. `trim` survives only as the emptiness test, where the whitespace is being counted rather
+// **Trimming happens with the expansion, and for the same reason.** Trimming here, after the
+// expansion, would make `--notify-message "…\n"` lose the newline its own escape had just produced.
+// `trim` survives only as the emptiness test, where the whitespace is being counted rather
 // than removed.
 function resolve_notify_message(raw_message: string | undefined): string {
 	if (raw_message === undefined || raw_message.trim().length === 0) return DEFAULT_NOTIFY_MESSAGE
@@ -66,7 +67,7 @@ function build_notify_config(input: {
 }
 
 // **`notes` is what the run has to say about itself beyond the message it was handed**, and today
-// that is the managed config-file report (joshuafolkken/kit#1592). It is a separate field rather than
+// that is the managed config-file report. It is a separate field rather than
 // text folded into `message`, because the message is the person's own completion summary and the
 // notes are the command's — folding them together would leave a caller unable to tell which half it
 // wrote. **A run with nothing to note adds no line at all**, blank separator included, so the
@@ -87,7 +88,8 @@ function build_completion_comment_body(input: {
 	notes?: ReadonlyArray<string>
 }): string {
 	const base_lines = [`✅ ${input.message}`]
-	const issue_lines = input.issue_number === undefined ? [] : [`Issue: #${input.issue_number}`]
+	const issue_lines =
+		input.issue_number === undefined ? [] : [`Issue: ${issue_cite.plain(input.issue_number)}`]
 	const pr_lines = input.pr_url === undefined ? [] : [`PR: ${input.pr_url}`]
 	const note_lines = note_section(input.notes)
 	const mention_lines = input.mentions.length === 0 ? [] : ['', input.mentions.join(' ')]

package/scripts/notify/telegram-notify.ts

@@ -13,16 +13,16 @@ const telegram_environment_schema = z.object({
 	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,
+// **`warning` is not `failure`**. 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
+// **`stalled` is not `warning`**. `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
+// **`stranded` is not `stalled`**. 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.
@@ -35,6 +35,7 @@ type TelegramTaskType =
 	| 'confirmation'
 	| 'stalled'
 	| 'stranded'
+	| 'progress'
 
 interface TelegramSendInput {
 	task_type: TelegramTaskType
@@ -64,6 +65,7 @@ const TASK_DEFINITIONS: Record<TelegramTaskType, TaskDefinition> = {
 	confirmation: { icon: '⏸️', label: 'Confirmation required' },
 	stalled: { icon: '⏳', label: 'Ready work is sitting undispatched' },
 	stranded: { icon: '🚨', label: 'Run stranded — nobody is driving it' },
+	progress: { icon: '📊', label: 'Progress' },
 }
 
 const NOTIFY_SWITCH_KEY = 'JOSH_NOTIFY'
@@ -82,9 +84,8 @@ function parse_environment_string(value: string | undefined): string {
 // 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.
+// down. Reporting the top line alone would exit non-zero with nothing a reader can act on.
+// 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
 
@@ -114,17 +115,14 @@ function describe_symptom(error: unknown): string {
 
 // 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).
+// this module, so no caller has to remember to do it.
 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.
+// **Missing credentials are a failure, not a skip**: a run with no credentials that returned quietly
+// would be indistinguishable from one whose notification arrived. `josh notify` and `josh followup`
+// load `.env` only optionally, so this is where the noise has to come from.
 //
 // 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.
@@ -143,10 +141,10 @@ function load_config(): TelegramConfig {
 	return { bot_token: result.data.telegram_bot_token, chat_id: result.data.telegram_chat_id }
 }
 
-// **An explicit opt-out is not a missing credential** (joshuafolkken/kit#2821). A consumer who never
-// meant to use Telegram had no way to say so, so every stop printed the #1564 failure as noise. Only
-// the stated value `off` disables the send: an unset or mistyped switch still falls through to
-// `load_config`, so a forgotten setup stays the loud failure #1564 made it.
+// **An explicit opt-out is not a missing credential**: a consumer who never means to use Telegram
+// says so, rather than seeing the missing-credential failure on every stop. Only the stated value
+// `off` disables the send: an unset or mistyped switch still falls through to `load_config`, so a
+// forgotten setup stays a loud failure.
 function is_notify_disabled(): boolean {
 	return parse_environment_string(process.env[NOTIFY_SWITCH_KEY]).toLowerCase() === NOTIFY_OFF_VALUE
 }
@@ -204,10 +202,9 @@ function head_of(body: string, kept: number): string {
 	return TRAILING_HIGH_SURROGATE.test(head) ? head.slice(0, -1) : head
 }
 
-// **The body is cut to fit Telegram's length limit, keeping its head** (joshuafolkken/kit#3242). A
-// warning carrying a whole driver stderr ran past 4096 characters and was refused with `400 Bad
-// Request`, so it reached nobody. A caller puts the cause first, so the tail is what is dropped, and the
-// header and the URLs around the body survive.
+// **The body is cut to fit Telegram's length limit, keeping its head**: a text past the limit is
+// refused with `400 Bad Request` and reaches nobody. A caller puts the cause first, so the tail is
+// what is dropped, and the header and the URLs around the body survive.
 function build_text(input: TelegramSendInput): string {
 	const text = join_blocks(input)
 	const overflow = text.length - TELEGRAM_TEXT_LIMIT
@@ -230,7 +227,7 @@ async function post_message(config: TelegramConfig, text: string): Promise<void>
 	}
 }
 
-// **The cause is re-wrapped rather than passed through** (joshuafolkken/kit#1564). The chain is kept,
+// **The cause is re-wrapped rather than passed through**. 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.
@@ -241,9 +238,8 @@ function build_send_failure(error: unknown, config: TelegramConfig): Error {
 }
 
 // **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.
+// this fails, so it throws and `pnpm josh notify` exits non-zero — a warning and exit 0 would make a
+// message that reached nobody look exactly like one that arrived.
 //
 // The failure it throws carries a `cause`, and that cause is redacted too — see `build_send_failure`.
 //
@@ -272,13 +268,12 @@ async function send(input: TelegramSendInput): Promise<void> {
 
 // **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.
+// Telegram is not a reason to leave a reviewed, green pull request unmerged. 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.
+// for a step that failed and was not allowed to end the run. A `⚠️` is what every routine notice
+// prints, so the failure would be buried under one.
 //
 // `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
@@ -326,7 +321,7 @@ interface WarningInput {
 /**
  * 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
+ * **One function rather than one per caller**. 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
@@ -354,8 +349,7 @@ interface ConfirmInput {
 
 /**
  * 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).
+ * on, a `backlogrun` that stopped needing a decision being the one this was written for.
  *
  * **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
@@ -384,8 +378,8 @@ interface StalledInput {
 }
 
 /**
- * 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
+ * Push the ⏳ stalled type — ready backlog work with a free lane that nothing has dispatched for a while.
+ * 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
@@ -413,8 +407,8 @@ interface StrandedInput {
 }
 
 /**
- * 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
+ * Push the 🚨 stranded type — a run whose driver is gone and which nothing can advance.
+ * 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.
  *
@@ -437,8 +431,30 @@ async function stranded(input: StrandedInput): Promise<boolean> {
 	)
 }
 
+/**
+ * Push the 📊 progress type — one `run:board` frame a person asked to receive periodically off-screen
+ * with `run:board --every`. Never a heartbeat: nothing sends it unasked.
+ *
+ * **`stranded`'s shape exactly**, with the board's own one-frame answer as the recovery — a frame lost
+ * to a Telegram timeout is read again by asking for it.
+ */
+async function progress(body: string): Promise<boolean> {
+	return await send_or_report(
+		{
+			task_type: 'progress',
+			repo_name: gh_spawn.get_repo_name_with_owner_within(REPO_LOOKUP_TIMEOUT_MS),
+			issue_title: undefined,
+			body,
+			issue_url: undefined,
+			pr_url: undefined,
+		},
+		'pnpm josh run:board --chat',
+	)
+}
+
 const telegram_notify = {
 	confirm,
+	progress,
 	send,
 	send_or_report,
 	stalled,

package/scripts/notify/telegram-test-logic.ts

@@ -44,7 +44,7 @@ function parse_task_type(raw: string | undefined): TelegramTaskType {
 
 // A flag counts as given only when it carries text, so `--issue-title ''` is not an answer. The
 // callers that *skip* a lookup because the flag already answered it read the same predicate, or the
-// two could disagree about an empty string and leave the field blank (joshuafolkken/kit#903).
+// two could disagree about an empty string and leave the field blank.
 // It is `cli_body`'s predicate rather than a second copy: the body flags are resolved there, and two
 // definitions of "given" would let `--body ''` count on one side and not the other.
 const has_flag_value = cli_body.has_value
@@ -56,8 +56,8 @@ function coalesce(primary: string | undefined, fallback: string | undefined): st
 }
 
 // `--body-file` is the form to reach for whenever the body carries a backtick or a `$`: inside shell
-// double quotes those are evaluated before this process starts, and the text runs
-// (joshuafolkken/kit#1198). The resolution itself is `cli_body`'s, shared with `josh followup`.
+// double quotes those are evaluated before this process starts, and the text runs.
+// The resolution itself is `cli_body`'s, shared with `josh followup`.
 function normalize_body(values: CliValues): string | undefined {
 	return cli_body.resolve({
 		inline: values.body,