@joshuafolkken/kit 1.1229.0 → 1.1370.0

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,

package/scripts/notify/telegram-test.ts

@@ -1,10 +1,10 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
-import { parseArgs } from 'node:util'
 import { git_gh_issue_read } from '#scripts/gh/git-gh-issue-read'
 import { git_gh_repo } from '#scripts/gh/git-gh-repo'
 import { github_issue_url, type IssueUrlTarget } from '#scripts/gh/github-issue-url'
 import { git_error } from '#scripts/git/git-error'
+import { session_cite } from '#scripts/issue/session-cite'
 import { josh_environment_file } from '#scripts/josh/josh-environment-file'
 import { cli_flags } from '#scripts/lib/cli-flags'
 import { telegram_notify } from './telegram-notify'
@@ -12,36 +12,44 @@ import { telegram_test_logic, type CliValues, type ResolvedContext } from './tel
 
 const REPO_NAME_SEPARATOR = '/'
 const ARGV_OFFSET = 2
+const FAILURE_EXIT_CODE = 1
+const USAGE =
+	'Usage: josh notify [--task-type <type>] [--body <text> | --body-file <path>] [--issue-url <url>] [--pr-url <url>] [--issue-title <text>] [--repo-name <name>]'
 
 // The free-text values a caller writes, often opening with a Markdown `-` bullet.
 const FREE_TEXT_FLAGS = ['--body', '--issue-title']
 
-function parse_cli_arguments(): CliValues {
-	const { values } = parseArgs({
-		args: [...cli_flags.attach_values(process.argv.slice(ARGV_OFFSET), FREE_TEXT_FLAGS)],
-		options: {
-			'task-type': { type: 'string' },
-			'repo-name': { type: 'string' },
-			'issue-title': { type: 'string' },
-			body: { type: 'string' },
-			'body-file': { type: 'string' },
-			'issue-url': { type: 'string' },
-			'pr-url': { type: 'string' },
-		},
-	})
-
-	return values
+const OPTIONS = {
+	'task-type': { type: 'string' },
+	'repo-name': { type: 'string' },
+	'issue-title': { type: 'string' },
+	body: { type: 'string' },
+	'body-file': { type: 'string' },
+	'issue-url': { type: 'string' },
+	'pr-url': { type: 'string' },
+} as const
+
+// `undefined` for a line nobody can read — an unknown flag, or a flag given no value.
+function parse_cli_arguments(): CliValues | undefined {
+	return cli_flags.values_of(
+		cli_flags.attach_values(process.argv.slice(ARGV_OFFSET), FREE_TEXT_FLAGS),
+		OPTIONS,
+	)
+}
+
+// A refused line sends nothing: the notification a misspelled flag would have produced is not the one
+// the caller wrote, and the non-zero exit is what tells a workflow it never went out.
+function refuse_usage(): void {
+	console.error(USAGE)
+	process.exitCode = FAILURE_EXIT_CODE
 }
 
 // The repository this notification is about, for the Telegram header.
 //
-// joshuafolkken/kit#1063: this used to spawn `gh repo view --json nameWithOwner` through a
-// promisified `execFile`, which is why joshuafolkken/kit#1022's survey never counted it — the
-// callee was not `execa` and the file was not `scripts/`. `gh repo view` goes through GraphQL and
-// is answered 403 in a cloud session, so the header simply lost its repository name there.
-//
-// The same fact is already read over REST by `git_gh_repo`, whose failure contract is the
-// `undefined` this caller was already handling, so it is read from there rather than from a second
+// Not `gh repo view`: it goes through GraphQL and is answered 403 in a cloud session, which would
+// lose the header's repository name there. The same fact is already read over REST by
+// `git_gh_repo`, whose failure contract is the `undefined` this caller handles, so it is read from
+// there rather than from a second
 // spawn (`CLAUDE.md` → "No clones").
 async function fetch_repo_name(): Promise<string | undefined> {
 	const name_with_owner = await git_gh_repo.repo_get_name_with_owner()
@@ -53,8 +61,7 @@ async function fetch_repo_name(): Promise<string | undefined> {
 
 // The title is read from the repository the URL names, through the same reader every other
 // cross-repository read goes through. Read unqualified, `gh` would answer with the issue of that
-// number in the working directory's repository — a different issue with a different title
-// (joshuafolkken/kit#903).
+// number in the working directory's repository — a different issue with a different title.
 //
 // A repository the token cannot read answers the same `undefined` as an issue that does not exist,
 // and the notification would then go out with no title line at all. Say so, so the gap is visible
@@ -65,7 +72,9 @@ async function fetch_issue_title(target: IssueUrlTarget | undefined): Promise<st
 	const title = await git_gh_issue_read.issue_get_title(target.issue_number, target.name_with_owner)
 
 	if (title === undefined) {
-		console.warn(`⚠️  Could not read ${target.name_with_owner}#${target.issue_number}.`)
+		console.warn(
+			`⚠️  Could not read ${session_cite.issue(target.issue_number, undefined, target.name_with_owner)}.`,
+		)
 	}
 
 	return title
@@ -90,9 +99,8 @@ async function resolve_issue_title(
 //
 // `--issue-url` outranks `--pr-url` because it identifies the issue the title is read from as well
 // as the repository. A pull URL answers the repository half only, which is why it is read for
-// `repo_name` and not passed to `resolve_issue_title` — a completion notification carrying only a
-// PR link used to go out under the working directory's repository while its link pointed elsewhere
-// (joshuafolkken/kit#994).
+// `repo_name` and not passed to `resolve_issue_title` — otherwise a completion notification carrying
+// only a PR link goes out under the working directory's repository while its link points elsewhere.
 async function resolve_context(values: CliValues): Promise<ResolvedContext> {
 	const target = github_issue_url.parse(values['issue-url'])
 	const pull_target = github_issue_url.parse_pull(values['pr-url'])
@@ -105,13 +113,20 @@ async function resolve_context(values: CliValues): Promise<ResolvedContext> {
 async function main(): Promise<void> {
 	josh_environment_file.load_environment_file()
 	const values = parse_cli_arguments()
+
+	if (values === undefined) {
+		refuse_usage()
+
+		return
+	}
+
 	const context = await resolve_context(values)
 	const input = telegram_test_logic.build_input({ values, context })
 
 	await telegram_notify.send(input)
 }
 
-// **A notification nobody received must not read as success** (joshuafolkken/kit#1564). This command
+// **A notification nobody received must not read as success**. This command
 // *is* the notification, so a failed send is its result and the exit code has to say so — the state
 // that Issue measured was three lost messages, each printing a warning and exiting 0.
 //

package/scripts/observations/observation-ledger-home.ts

@@ -7,10 +7,10 @@ import { observation_ledger_migrate } from './observation-ledger-migrate'
 
 // Where the observation ledger is read and written, whichever work tree a command runs in.
 //
-// **The ledger lives in the work tree the command runs in — a lane's in a lane** (joshuafolkken/kit#2919).
-// It used to resolve to the primary checkout from every lane (joshuafolkken/kit#2419), so a lane's
-// lines waited there for a batch-end flush; another run's stash of that checkout took them, the flush
-// read `git status` and found nothing, and the lines were lost. Each run now appends to its own
+// **The ledger lives in the work tree the command runs in — a lane's in a lane**.
+// Resolved to the primary checkout from every lane, a lane's lines would wait there for a batch-end
+// flush; another run's stash of that checkout would take them, the flush would read `git status` and
+// find nothing, and the lines would be lost. Each run appends to its own
 // issue's file in its own tree, `git-staging.ts` commits it with the run, and `pnpm josh followup`
 // commits whatever was appended after that commit before it merges — so a lane's lines reach the
 // default branch with the lane's own pull request, and the primary checkout holds none of them.
@@ -21,8 +21,7 @@ function ledger_root(cwd: string = process.cwd()): string {
 	return cwd
 }
 
-// **Resolving the directory migrates the single-file ledgers first** (joshuafolkken/kit#2724,
-// joshuafolkken/kit#2919). Every reader and writer asks here — `review:record --check`,
+// **Resolving the directory migrates the single-file ledgers first**. Every reader and writer asks here — `review:record --check`,
 // `review:findings`, the retrospective, the stash carry's duplicate check — so none of them can read a
 // directory without the lines that still sit at an old path, which for the review-record check would
 // answer `missing` for a round recorded before the move.
@@ -52,6 +51,12 @@ async function current_branch(cwd: string): Promise<string> {
 	}
 }
 
+// The `<YYYY-MM-DD>` a ledger line carries, and the name of a date file — one spelling for every
+// writer, so a line and the file it lands in never disagree about the day.
+function ledger_date(now: Date): string {
+	return now.toISOString().slice(0, DATE_END)
+}
+
 // **The file a writer that names no issue appends to** — the issue the checked-out branch leads with
 // (`2919-lane`, `2919-store-the-ledger`), so a lane's lines land in its own issue's file; or the date,
 // for a line written on the default branch outside any issue's run, which `pnpm josh
@@ -59,7 +64,7 @@ async function current_branch(cwd: string): Promise<string> {
 async function writer_path(now: Date, cwd: string = process.cwd()): Promise<string> {
 	const issue = git_branch.issue_from_branch(await current_branch(cwd))
 
-	return file_path(issue ?? now.toISOString().slice(0, DATE_END), cwd)
+	return file_path(issue ?? ledger_date(now), cwd)
 }
 
 // A file whose last line has no newline would otherwise run into the next file's first line.
@@ -104,7 +109,7 @@ async function read(cwd: string = process.cwd()): Promise<string | undefined> {
 
 // The one append every ledger writer goes through. A consumer that does not keep the ledger has no
 // `docs/` at its root, so the parent is created first — the one write path that can bring the ledger
-// into existence there (joshuafolkken/kit#2402).
+// into existence there.
 async function append(target: string, lines: ReadonlyArray<string>): Promise<void> {
 	if (lines.length === 0) return
 
@@ -115,6 +120,7 @@ async function append(target: string, lines: ReadonlyArray<string>): Promise<voi
 const observation_ledger_home = {
 	append,
 	issue_path,
+	ledger_date,
 	ledger_root,
 	read,
 	writer_path,

package/scripts/observations/observation-ledger-line.ts

@@ -1,8 +1,8 @@
 // The observation ledger's line grammar (`.claude/skills/workflow-commands/observation-ledger.md`)
 // is fixed — `- k:<slug> | d<n> | <YYYY-MM-DD> | <where> | <what>` — but the path was collected in
 // `observation-ledger.ts` without a line ever being parsed, so a malformed append rode a flush
-// through unremarked. This validates a ledger entry line and reports why a broken one is broken
-// (joshuafolkken/kit#2123). The grammar is the single source's, pinned by the document test.
+// through unremarked. This validates a ledger entry line and reports why a broken one is broken.
+// The grammar is the single source's, pinned by the document test.
 
 const KEY_PREFIX = '- k:'
 const FIELD_SEPARATOR = ' | '
@@ -96,6 +96,7 @@ function missing_lines(candidates: ReadonlyArray<string>, ledger: string): Array
 const observation_ledger_line = {
 	broken_ledger_lines,
 	is_ledger_entry_line,
+	line_reason,
 	missing_lines,
 }
 

package/scripts/observations/observation-ledger-migrate.ts

@@ -19,9 +19,8 @@ import {
 } from './observation-ledger'
 import { observation_ledger_line } from './observation-ledger-line'
 
-// Moves the ledger's lines from the single files it was before joshuafolkken/kit#2919 into the
-// directory it is now, as `legacy.md` (`observation-ledger.ts` carries why the old paths are still
-// recognized). Changing a constant alone splits the appends: a run still on the old code recreates the
+// Moves the ledger's lines from its old single files into the directory, as `legacy.md`
+// (`observation-ledger.ts` carries why the old paths are still recognized). Changing a constant alone splits the appends: a run still on the old code recreates the
 // old file, and a consumer repository's existing ledger stays where nothing reads it. So resolving the
 // ledger migrates first (`observation-ledger-home.ts`), and whatever reached an old path lands in the
 // directory before anything reads or appends.
@@ -164,7 +163,7 @@ function legacy_directory_names(directory: string): ReadonlyArray<string> {
 	}
 }
 
-// **The old directory moves file by file into the same names** (joshuafolkken/kit#3341), so an
+// **The old directory moves file by file into the same names**, so an
 // issue's lines stay in that issue's file; the emptied directory is removed when nothing else is left.
 function migrate_directory(root: string): boolean {
 	const legacy_directory = path.join(root, LEGACY_OBSERVATION_LEDGER_DIRECTORY)

package/scripts/observations/observation-ledger-prepare.ts

@@ -1,12 +1,12 @@
 import { observation_ledger_home } from './observation-ledger-home'
 import { observation_ledger_line, type BrokenLine } from './observation-ledger-line'
 
-// **What has to hold before a ledger line is committed, asked by every path that commits one**
-// (joshuafolkken/kit#2763): `pnpm josh observations:flush`, the run's own commit in
+// **What has to hold before a ledger line is committed, asked by every path that commits one**:
+// `pnpm josh observations:flush`, the run's own commit in
 // `scripts/git/git-staging.ts` and `pnpm josh followup`'s pre-merge ledger commit. Lines still on an
-// old path are moved first (joshuafolkken/kit#2724, joshuafolkken/kit#2919), so the commit carries the
+// old path are moved first, so the commit carries the
 // move and the lines together, and every entry line is then parsed against the grammar
-// (joshuafolkken/kit#2123) — each caller decides what a broken line costs it.
+// — each caller decides what a broken line costs it.
 //
 // **A ledger that is not there has no line to break** — the change a status saw is then its deletion,
 // and a commit carries that like any other change to it.

package/scripts/observations/observation-ledger.ts

@@ -1,20 +1,20 @@
 // The observation ledger's one location, named here rather than inside any of the places that act on
-// it (joshuafolkken/kit#1756). `git-staging.ts` stages it with the run's own commit when its grammar
-// holds (joshuafolkken/kit#2763), `hook-gate-reuse.ts` excludes it from what a hook calls a carried
+// it. `git-staging.ts` stages it with the run's own commit when its grammar
+// holds, `hook-gate-reuse.ts` excludes it from what a hook calls a carried
 // tree, and `observations-flush.ts` commits what no run carried — so a literal in each would be three
 // answers to one question, and a rename reaching only some of them would silently split them.
 //
-// **It sits outside `docs/`** (joshuafolkken/kit#3341): its files are machine-written data lines, not
-// documents a person reads, and at about forty new files a day they were most of `docs/`.
+// **It sits outside `docs/`**: its files are machine-written data lines, not
+// documents a person reads, and at about forty new files a day they would be most of `docs/`.
 //
-// **It is a directory of one file per issue, not one file** (joshuafolkken/kit#2919). One file every
-// run appended to made two lanes' pull requests conflict at its tail, so lanes parked their lines in
-// the primary checkout for a batch-end flush — and another run's stash took them from there, and the
-// flush never saw them. A run now appends to `<issue>.md` in its own work tree and merges it with its
-// own pull request: parallel lanes write different files, so nothing conflicts and nothing waits.
+// **It is a directory of one file per issue, not one file**. One file every run appends to makes two
+// lanes' pull requests conflict at its tail, and parking the lines in the primary checkout for a
+// batch-end flush lets another run's stash take them before the flush sees them. A run appends to
+// `<issue>.md` in its own work tree and merges it with its own pull request: parallel lanes write
+// different files, so nothing conflicts and nothing waits.
 const OBSERVATION_LEDGER_DIRECTORY = '.josh/observations'
 
-// Where the directory lived until joshuafolkken/kit#3341, a migration source for the same reasons as
+// The directory's previous location, a migration source for the same reasons as
 // the single-file ledgers below: each `<name>.md` in it moves to the same name in the directory.
 const LEGACY_OBSERVATION_LEDGER_DIRECTORY = 'docs/maintainers/observations'
 
@@ -29,10 +29,9 @@ const LEDGER_FILE_EXTENSION = '.md'
 // lost to the split.
 const LEGACY_LEDGER_FILE = `legacy${LEDGER_FILE_EXTENSION}`
 
-// Where the ledger lived as one file — `docs/observations.md` before joshuafolkken/kit#2724 and
-// `docs/maintainers/observations.md` until joshuafolkken/kit#2919 — kept as migration sources rather
-// than forgotten: a run still on the old code, a stash cut before the move and a consumer repository's
-// existing ledger all write there, and `observation-ledger-migrate.ts` moves what it finds into the
+// The single-file ledger paths, `docs/observations.md` and `docs/maintainers/observations.md`, kept
+// as migration sources rather than forgotten: a run still on the old code, a stash cut before the
+// move and a consumer repository's existing ledger all write there, and `observation-ledger-migrate.ts` moves what it finds into the
 // directory. Every place that recognizes the ledger recognizes them, so a line on either path is never
 // staged into an ordinary commit. Remove them once every repository holding a ledger has migrated.
 const LEGACY_OBSERVATION_LEDGER_PATHS: ReadonlyArray<string> = [
@@ -105,7 +104,7 @@ function ledger_paths(status_output: string): ReadonlyArray<string> {
 
 // **The one place that answers "does this working tree hold a pending observation append?"**
 // `observations-flush.ts`'s `has_ledger_change` and `pnpm josh followup`'s pre-merge ledger commit
-// both ask it (joshuafolkken/kit#1810), so a literal in each would be the clone the header above
+// both ask it, so a literal in each would be the clone the header above
 // warns against. A blank porcelain line carries no ledger path, so `is_ledger_line` answers false for
 // it and no filtering is needed.
 function has_pending_append(status_output: string): boolean {

package/scripts/observations/observation-record-cli.ts

@@ -0,0 +1,83 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { cli_flags } from '#scripts/lib/cli-flags'
+import { observation_ledger_home } from './observation-ledger-home'
+import {
+	observation_record,
+	REFUSED_VERDICT,
+	type ObservationEntry,
+	type RecordResult,
+} from './observation-record'
+
+// `josh observation:record <key> <depth> <where> <what>` — count the key's earlier sightings, append
+// this one, and answer what the run does next. Exactly one token on stdout:
+// `file` on the second sighting, which the promotion rule files; `ledger` on any other, which the line
+// alone records. The earlier sightings and the file written go to stderr, so the Issue a `file` answer
+// opens can quote the first sighting's date from them.
+
+const ARGV_OFFSET = 2
+const FAILURE_EXIT_CODE = 1
+const ENTRY_FIELDS = 4
+const USAGE = 'Usage: josh observation:record <key> <depth> <where> <what> [--checkout <path>]'
+const OPTIONS = { checkout: { type: 'string' } } as const
+
+interface RecordArguments {
+	entry: ObservationEntry
+	checkout: string
+}
+
+function entry_of(fields: ReadonlyArray<string>): ObservationEntry {
+	const [slug = '', depth = '', where = '', what = ''] = fields
+
+	return { slug, depth, where, what }
+}
+
+function parse_arguments(argv: ReadonlyArray<string>): RecordArguments | undefined {
+	const parsed = cli_flags.arguments_of(argv, OPTIONS)
+
+	if (parsed?.positionals.length !== ENTRY_FIELDS) return undefined
+
+	const { checkout } = parsed.values
+
+	return {
+		entry: entry_of(parsed.positionals),
+		checkout: checkout ?? observation_ledger_home.ledger_root(),
+	}
+}
+
+function report(result: RecordResult): number {
+	if (result.verdict === REFUSED_VERDICT) {
+		console.error(`Refused: ${result.reason}\n${USAGE}`)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const sighting = `${String(result.earlier.length)} earlier sighting(s); appended to ${result.target}`
+
+	console.error([sighting, ...result.earlier].join('\n'))
+	console.info(result.verdict)
+
+	return 0
+}
+
+async function run(argv: ReadonlyArray<string>, now: Date): Promise<number> {
+	const parsed = parse_arguments(argv)
+
+	if (parsed === undefined) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	return report(await observation_record.record({ ...parsed, now }))
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv, new Date())
+}
+
+const observation_record_cli = { USAGE, run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { observation_record_cli }