@joshuafolkken/kit 1.1229.0 → 1.1370.0

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

@@ -13,11 +13,10 @@ import { run_progress_clock } from './run-progress-clock'
 import { run_progress_read, type ObservationRead } from './run-progress-read'
 
 // `josh run:progress` — the background watcher that breaks a long silence with one line of
-// observations, and `--mark`, which tells its clock that a real report just happened
-// (joshuafolkken/kit#1520).
+// observations, and `--mark`, which tells its clock that a real report just happened.
 //
 // **This is the one josh command that is meant to be started and left running.** Every other one
-// answers once and the parent's own loop drives it; that shape was rejected here on purpose, because
+// answers once and the parent's own loop drives it; that shape does not fit here, because
 // a parent that waits and reports spends one of its own turns per heartbeat — 36 of them in a
 // three-hour run, taken at the point its context is largest. So the loop lives here, the parent
 // starts it in the background, and all the parent does is relay what appears.
@@ -30,7 +29,8 @@ import { run_progress_read, type ObservationRead } from './run-progress-read'
 // **It cannot send a Telegram.** That is structural rather than a promise — nothing here imports
 // `scripts/notify/telegram-notify`, which is the only egress there is. A heartbeat every twenty minutes on
 // a phone is notification fatigue, and it would cheapen the `confirmation` and `completion` messages
-// that do need to interrupt someone.
+// that do need to interrupt someone. Only an explicit `run:board --every <minutes>`, started because a
+// person asked for periodic progress off-screen, sends one.
 
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
@@ -52,20 +52,19 @@ const DECLINE_RETRY_SECONDS = 120
 // The clock a fresh loop starts with: nothing has declined yet, so nothing is being waited out.
 const NO_RETRY = 0
 const { DEFAULT_WAIT_MAX_HOURS } = run_progress_args
-const ENVIRONMENT_KEY = 'JOSH_PROGRESS'
-const DISABLED_VALUE = '0'
+const { DISABLED_KEY, DISABLED_VALUE, is_disabled } = run_progress
 
-// joshuafolkken/kit#2480: a malformed `--wait` exits at once, and read as "started" it left a person
-// without progress until someone looked at the exit — so the refusal says the relay is down.
+// A malformed `--wait` exits at once, and read as "started" it would leave a person without progress
+// until someone looked at the exit — so the refusal says the relay is down.
 const USAGE =
 	'Usage: josh run:progress [--repo <owner/repo>] [--interval <minutes>] [--output <path>] [--once | --wait] [--hours <hours>] | josh run:progress --mark | josh run:progress --path\nThe progress watcher did not start, so nothing is relaying progress to this session — fix the arguments (one flag and one value per argument) and start it again.'
-const DISABLED_NOTICE = `\`${ENVIRONMENT_KEY}=${DISABLED_VALUE}\` is set, so no progress is reported.`
+const DISABLED_NOTICE = `\`${DISABLED_KEY}=${DISABLED_VALUE}\` is set, so no progress is reported.`
 const MARKED_NOTICE =
 	'Recorded a report at this moment. The next progress line waits a full interval from here, so a heartbeat cannot land immediately behind a real report.'
 // A dispatched lane child carries `JOSH_LANE_CHILD`, and only the outermost run reports progress — a
-// child that started a watcher of its own would be the second one this command's whole design refuses
-// (joshuafolkken/kit#1947). The decision used to live in prose the child read as "start none"; the mark
-// makes it mechanical, so a bare `fullrun #N` handed to a lane no longer reads itself as outermost.
+// child that started a watcher of its own would be the second one this command's whole design refuses.
+// The mark makes that mechanical, so a bare `fullrun #N` handed to a lane does not read itself as
+// outermost.
 const LANE_CHILD_NOTICE =
 	'This session is a dispatched lane child (`JOSH_LANE_CHILD`), so no progress watcher is started — the outermost run reports for every child.'
 const IDLE_NOTICE =
@@ -74,15 +73,14 @@ const UNREADABLE_NOTICE =
 	'The `in-progress` listing could not be read, so nothing is reported. That is not "nothing is running" — check `gh auth status` and ask again.'
 const FAILED_TICK_PREFIX =
 	'A progress reading failed, so nothing is reported for it. The watcher is still running, and will read again after the cooldown:'
-const WAIT_EXPIRED_NOTICE = `The watch bound (\`--hours\`, ${String(DEFAULT_WAIT_MAX_HOURS)} by default for \`--wait\`) ran out with no newly runnable work arriving. Every report it made is already on the run's event stream (\`pnpm josh run:event --watch\`), so there is nothing to relay. Starting another \`--wait\` resumes the same clock.`
+const WAIT_EXPIRED_NOTICE = `The watch bound (\`--hours\`, ${String(DEFAULT_WAIT_MAX_HOURS)} by default for \`--wait\`) ran out with no newly runnable work arriving. Every report it made is already on the run's event stream, which the \`pnpm josh run:board\` pane draws, so there is nothing to relay. Starting another \`--wait\` resumes the same clock.`
 // The repository name is only ever printed, never written against, so the bounded lookup is the right
 // one: a `gh` call that hangs would otherwise block the synchronous read at startup and leave the
 // watcher neither running nor saying so.
 const REPO_LOOKUP_TIMEOUT_SECONDS = 10
 const REPO_LOOKUP_TIMEOUT_MS = REPO_LOOKUP_TIMEOUT_SECONDS * run_progress.MS_PER_SECOND
 // A lookup that timed out or failed is not an argument the caller got wrong, so it is told apart from
-// the usage error — read as one, it sent a person to fix arguments that were correct
-// (joshuafolkken/kit#2859).
+// the usage error — read as one, it would send a person to fix arguments that were correct.
 const REPO_UNRESOLVED_NOTICE = `The repository could not be resolved (\`gh\` did not answer within ${String(REPO_LOOKUP_TIMEOUT_SECONDS)}s or failed), so the progress watcher did not start. Pass \`--repo <owner/repo>\` and start it again.`
 
 const DECLINE_NOTICES: Readonly<Record<'idle' | 'unreadable', string>> = {
@@ -105,8 +103,7 @@ interface WatchOptions {
 	repo: string
 	tick_ms: number
 	// `--wait` alone: the line goes to the run's event stream and the ambient log, never to standard
-	// output, because a background command's output reaches the session only as a wake
-	// (joshuafolkken/kit#3102).
+	// output, because a background command's output reaches the session only as a wake.
 	is_stream_only?: boolean
 }
 
@@ -120,8 +117,7 @@ type DeclineKind = Exclude<ObservationRead['kind'], 'observed'>
 
 // A union rather than an optional field, so a caller that wants the reason has to establish that
 // there is one — the reason exists exactly when no line went out. `line` is the exact string printed,
-// handed back so the caller can persist it verbatim for `josh run:wake --list` to relay
-// (joshuafolkken/kit#1910).
+// handed back so the caller can persist it verbatim for `josh run:wake --list` to relay.
 type EmitResult = { kind: DeclineKind } | { kind: 'observed'; state: ProgressState; line: string }
 
 interface WatchLoop {
@@ -141,10 +137,6 @@ const FRESH_LOOP: Omit<WatchLoop, 'last_ms'> = {
 	state: undefined,
 }
 
-function is_disabled(): boolean {
-	return process.env[ENVIRONMENT_KEY] === DISABLED_VALUE
-}
-
 function report_usage(): number {
 	console.error(USAGE)
 
@@ -197,7 +189,7 @@ async function emit(options: WatchOptions, context: EmitContext): Promise<EmitRe
 	const state = run_progress.next_state(context.state, key, context.now_ms)
 
 	// The interval reaches the line from the options rather than being resolved a second time, so the
-	// schedule printed and the clock `step` consults are one number (joshuafolkken/kit#1726). Both
+	// schedule printed and the clock `step` consults are one number. Both
 	// reporting forms come through here, which is what puts the field on `--wait` and `--once` alike.
 	const line = run_progress.format_line(read.observations, {
 		interval_ms: options.interval_ms,
@@ -261,7 +253,7 @@ async function attempt(
  * print one straight after the run's real report — which is the single thing this command is built
  * not to do.
  *
- * **A tick that printed nothing does not move the report clock.** A decline now means no run has
+ * **A tick that printed nothing does not move the report clock.** A decline means no run has
  * started here at all, so the silence has not been broken and the first report is emitted at once
  * instead of waiting out an interval spent idle; what a decline moves instead is the read cooldown.
  */
@@ -292,9 +284,9 @@ async function step(options: WatchOptions, target: string, loop: WatchLoop): Pro
  * The loop both reporting forms are, with one difference between them.
  *
  * `watch` runs until `--hours` expires; `--wait` stops at the first arrival and keeps its lines off
- * standard output (joshuafolkken/kit#3102). Everything else — where the clock is seeded from, the tick, the decline
- * cooldown `step` keeps — is one implementation on purpose: two copies would let a fix to the bound or
- * to the initial silence reach one form and not the other, and `--wait` is the form a run starts.
+ * standard output. Everything else — where the clock is seeded from, the tick, the decline cooldown
+ * `step` keeps — is one implementation on purpose: two copies would let a fix to the bound or to the
+ * initial silence reach one form and not the other, and `--wait` is the form a run starts.
  */
 // The silence this loop starts from: the record where there is one, and otherwise the moment it began
 // watching, so a first line on a tree with no record reports the wait it actually did.
@@ -304,11 +296,11 @@ function seed_loop(target: string, started_ms: number): WatchLoop {
 
 // Why the loop stopped, so `drive` prints the bound-expired notice only when the bound is what
 // expired — not when `josh followup` ended the watcher, which is a clean stop with nothing to report.
-// `arrived` is a `--wait` ended early by newly runnable work (joshuafolkken/kit#2503).
+// `arrived` is a `--wait` ended early by newly runnable work.
 type WatchExit = 'arrived' | 'ended' | 'bound'
 
 // `wait` is present for `--wait` alone, which ends at the first arrival its probe sees. **A report is
-// not an exit** (joshuafolkken/kit#3102): every exit wakes the session that started it, and a wake
+// not an exit**: every exit wakes the session that started it, and a wake
 // spent relaying a line the event stream already carries is the most expensive turn a run takes, so
 // only what the parent has to act on ends the wait.
 async function wait_exit(wait: ArrivalProbe | undefined): Promise<WatchExit | undefined> {
@@ -334,10 +326,9 @@ function final_exit(life: string): WatchExit {
 }
 
 // The loop both reporting forms share, reading its own liveness record at the top of each pass — the
-// `run-wake-loop.ts` `run_loop` shape (joshuafolkken/kit#1727). A record gone means `josh followup`
-// removed it at the merge, so the watcher stops at once instead of waiting out its bound
-// (joshuafolkken/kit#1821); `--wait` also stops at the first arrival, and otherwise the loop runs
-// until `--hours` expires.
+// `run-wake-loop.ts` `run_loop` shape. A record gone means `josh followup` removed it at the merge,
+// so the watcher stops at once instead of waiting out its bound; `--wait` also stops at the first
+// arrival, and otherwise the loop runs until `--hours` expires.
 async function run_ticks(
 	options: WatchOptions,
 	target: string,
@@ -370,8 +361,8 @@ async function drive(options: WatchOptions, is_wait: boolean): Promise<number> {
 	const exit = await run_ticks(options, target, life, wait)
 
 	if (exit === 'bound' && is_wait) console.error(WAIT_EXPIRED_NOTICE)
-	// Every `--wait` exit is a wake, so it carries the pick-up reading with it (joshuafolkken/kit#2452) —
-	// the reading an `arrived` exit was woken for.
+	// Every `--wait` exit is a wake, so it carries the pick-up reading with it — the reading an
+	// `arrived` exit was woken for.
 	if (is_wait) await backlog_ready.print_ready_line()
 
 	return SUCCESS_EXIT_CODE
@@ -398,31 +389,28 @@ async function once(options: WatchOptions): Promise<number> {
 }
 
 /**
- * The form a run starts in the background: it reports on its own and wakes the caller only for work
- * (joshuafolkken/kit#3102).
+ * The form a run starts in the background: it reports on its own and wakes the caller only for work.
  *
- * **A report is not a wake.** It once ended at its first line so a harness that delivers a background
- * command's output only on exit would relay it (joshuafolkken/kit#1576) — which cost the orchestrating
- * session one turn per heartbeat, re-reading a hundred thousand tokens of context to pass on a line it
- * was forbidden to change. Every line already reaches the run's event stream as a `heartbeat` and the
- * ambient log, which a person's `run:event --watch` pane reads with no model in between, so this form
- * keeps its lines off standard output and exits only on an arrival, on `josh followup` ending its life
- * record, or on its bound. The caller starts it once and restarts it only after one of those.
+ * **A report is not a wake.** Ending at each line would cost the orchestrating session one turn per
+ * heartbeat, re-reading its whole context to pass on a line it may not change. Every line already
+ * reaches the run's event stream as a `heartbeat` and the ambient log, which a person's `run:board`
+ * pane reads with no model in between, so this form keeps its lines off standard output and exits
+ * only on an arrival, on `josh followup` ending its life record, or on its bound. The caller starts it
+ * once and restarts it only after one of those.
  *
  * **The clock is still this command's, not the caller's.** It is the watch loop itself, a tick at a
  * time, rather than a second reading of the same record — so a real report elsewhere pushes the next
- * line out and a declined reading takes the same cooldown. That is what keeps joshuafolkken/kit#1570
- * intact: the caller arms no timer of its own.
+ * line out and a declined reading takes the same cooldown, and the caller arms no timer of its own.
  *
  * **One at a time is the caller's part rather than this loop's.** The record is read before the `gh`
  * reads and written after them, so two of these running at once could both find the same silence due
  * and both print; `backlogrun.md` starts exactly one, which is where that is guaranteed.
  *
- * **A decline is not an exit.** A decline now means no run has started here at all — no hold, no
+ * **A decline is not an exit.** A decline means no run has started here at all — no hold, no
  * carried budget, no lane, and no `in-progress` child — so a genuinely idle repository keeps the loop
  * waiting instead of ending it; returning there would hand the caller an instant answer to restart,
  * and the documented restart makes that a poll rather than a heartbeat. Once a run has started the
- * loop reports even before the first child carries `in-progress` (joshuafolkken/kit#1900).
+ * loop reports even before the first child carries `in-progress`.
  */
 async function wait_once(options: WatchOptions): Promise<number> {
 	return await drive({ ...options, is_stream_only: true }, true)
@@ -436,7 +424,7 @@ async function mark_now(): Promise<number> {
 }
 
 // The ambient log's path on standard output, so a person can `tail -F` the surface the heartbeat keeps
-// across a session cut (joshuafolkken/kit#2156). It reads no run state, so it answers even before one
+// across a session cut. It reads no run state, so it answers even before one
 // has started and in a lane child alike — the path is a function of the checkout, not of a live run.
 async function report_path(): Promise<number> {
 	console.info(await run_progress_read.log_target())
@@ -497,6 +485,7 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 }
 
 const run_progress_cli = {
+	DECLINE_RETRY_SECONDS,
 	DEFAULT_WAIT_MAX_HOURS,
 	DISABLED_NOTICE,
 	FAILED_TICK_PREFIX,

package/scripts/run/progress/run-progress-clock.ts

@@ -1,12 +1,12 @@
 import { git_common_directory } from '#scripts/git/git-common-directory'
 import { stamp_file } from '#scripts/josh/stamp-file'
 import { error_text } from '#scripts/lib/error-message'
+import { json_value } from '#scripts/lib/json-value'
 import { z } from 'zod'
 
-// The report clock `josh run:progress` keeps, in the one form both of its readers can use
-// (joshuafolkken/kit#1570).
+// The report clock `josh run:progress` keeps, in the one form both of its readers can use.
 //
-// **It exists because a second reader arrived, and that one cannot await.** The watcher reads the
+// **One of its two readers cannot await.** The watcher reads the
 // record between ticks, where an `async` call costs nothing; the trigger-delivered rule that refuses
 // an early heartbeat (`scripts/rules/early-heartbeat.ts`) reads it inside a `PreToolUse` hook, whose
 // decision is synchronous from payload to envelope. Copying the record's shape into the hook would be
@@ -26,17 +26,17 @@ const PROGRESS_PREFIX = 'josh-run-progress-'
 // run last reported and is written on every heartbeat, so it can never double as "should this watcher
 // still be running". This one is presence-only — the watcher writes it once when it begins, reads it
 // every tick, and ends the moment it is gone, which is how `josh followup` stops a watcher at the
-// merge instead of leaving it to wait out its whole bound (joshuafolkken/kit#1821). It reuses the same
-// key as the report clock — the work tree's own git directory — so both name one file per run.
+// merge instead of leaving it to wait out its whole bound. It reuses the same key as the report clock
+// — the work tree's own git directory — so both name one file per run.
 //
 // **The loop that reads its own record and exits when it is gone is `run-wake-loop.ts`'s `run_loop`
-// pattern (joshuafolkken/kit#1727), and the read/write is `stamp_file`.** Neither is re-implemented
+// pattern, and the read/write is `stamp_file`.** Neither is re-implemented
 // here: this module only names the record, exactly as it names the report clock. Unlike `run-hold`'s
 // and `run-carry`'s records it needs no expiry, because it is read only by the one watcher that wrote
 // it — never by another run deciding whether a resource is free — so a fresh watcher always overwrites
 // a stale one and there is no cross-run read to fall open.
 const LIFE_PREFIX = 'josh-run-progress-life-'
-// **The ambient surface the heartbeat keeps across a session cut** (joshuafolkken/kit#2156). The report
+// **The ambient surface the heartbeat keeps across a session cut.** The report
 // clock holds only the *last* line, which `josh run:wake --list` relays on demand — a person has to
 // type for it, so after a cut the heartbeat sits at the *requested* tier. This log mirrors every
 // heartbeat line into a plain-text file beside the clock, so a person who keeps `tail -F` open on it
@@ -59,7 +59,7 @@ const BLOCK_SEPARATOR = '\n\n'
 
 // `line` is the last heartbeat the watcher printed, kept verbatim beside the clock so a reader that
 // cannot see the watcher's transcript — a person checking a woken headless `backlogrun` through
-// `josh run:wake --list` — still reads the exact line it emitted (joshuafolkken/kit#1910). It is
+// `josh run:wake --list` — still reads the exact line it emitted. It is
 // optional because a bare `--mark` moves the clock without producing one, and because a record written
 // before this field existed carries only `reported_at`.
 const report_stamp_schema = z.object({ reported_at: z.string(), line: z.string().optional() })
@@ -78,18 +78,14 @@ function parse_stamp(raw: string): number | undefined {
  * The last heartbeat line the watcher persisted, or `undefined` for an absent, unparsable, or
  * pre-`line` record. This is what `josh run:wake --list` relays to a person who is no longer the parent
  * session — the headless parent woken after a cut prints its progress only to its own transcript, and
- * this record is the one place that line survives (joshuafolkken/kit#1910).
+ * this record is the one place that line survives.
  */
 function read_last_line(target: string): string | undefined {
 	const raw = stamp_file.read_stamp_text(target)
 
 	if (raw === undefined) return undefined
 
-	try {
-		return report_stamp_schema.safeParse(JSON.parse(raw)).data?.line
-	} catch {
-		return undefined
-	}
+	return json_value.parse_with(raw, report_stamp_schema)?.line
 }
 
 /**
@@ -112,13 +108,13 @@ function read_last_report(target: string): number | undefined {
 }
 
 // The ambient log's path, a sibling of the report clock so one directory names both and the CLI can
-// derive it from the clock target alone (joshuafolkken/kit#2156).
+// derive it from the clock target alone.
 function log_path_of(target: string): string {
 	return `${target}${LOG_SUFFIX}`
 }
 
-// **Staleness is read from the report clock's own last timestamp, not the log file's mtime**
-// (joshuafolkken/kit#2156). The clock's `reported_at` is the run's own clock — a copy or a backup can
+// **Staleness is read from the report clock's own last timestamp, not the log file's mtime.** The
+// clock's `reported_at` is the run's own clock — a copy or a backup can
 // move a file's mtime, and a fresh run whose first heartbeat found a previous run's log would then
 // append to it. It is read before `mark` overwrites the clock, so it sees the *previous* report.
 function is_log_stale(target: string, now_ms: number): boolean {
@@ -162,10 +158,9 @@ function append_line(
 
 // A heartbeat carries its line; a bare `--mark` (a real report resetting the clock) carries none and
 // **preserves the line already there** rather than blanking it — so `josh run:wake --list` keeps
-// showing the most recent heartbeat between a run's real reports rather than going empty on every one
-// (joshuafolkken/kit#1910). A carried line is also mirrored into the ambient log — the surface a person
-// keeps open across a cut — before the clock is overwritten, so staleness sees the previous report
-// (joshuafolkken/kit#2156).
+// showing the most recent heartbeat between a run's real reports rather than going empty on every one.
+// A carried line is also mirrored into the ambient log — the surface a person keeps open across a cut
+// — before the clock is overwritten, so staleness sees the previous report.
 function mark(target: string, now_ms: number, line?: string): void {
 	const reported_at = new Date(now_ms).toISOString()
 	const kept = line ?? read_last_line(target)
@@ -177,9 +172,8 @@ function mark(target: string, now_ms: number, line?: string): void {
 	stamp_file.write_stamp(target, kept === undefined ? { reported_at } : { reported_at, line: kept })
 }
 
-// `undefined` is passed straight through so `stamp_file`'s own default root stands, which is what the
-// caller got before this function existed. Hashing an empty string instead would key the record on a
-// path no other code path produces.
+// `undefined` is passed straight through so `stamp_file`'s own default root stands. Hashing an empty
+// string instead would key the record on a path no other code path produces.
 function stamp_target_of(git_directory: string | undefined): string {
 	return stamp_file.stamp_path(PROGRESS_PREFIX, git_directory)
 }
@@ -193,10 +187,9 @@ function life_target_of(git_directory: string | undefined): string {
 
 // **`pinged_at` is written by every tick and checked by `is_life_fresh`.** Without it the life record
 // is presence-only — existence is the only signal, and a record from a watcher that stopped an hour
-// ago is indistinguishable from one whose watcher is live. Adding `pinged_at` to the payload lets a
-// guard detect "children in-flight but watcher stale" without a second file (joshuafolkken/kit#2113).
-// Old records carrying only `{ alive: true }` parse successfully; `pinged_at` is optional on read,
-// which is what makes this backward-compatible.
+// ago is indistinguishable from one whose watcher is live. `pinged_at` in the payload lets a guard
+// detect "children in-flight but watcher stale" without a second file. It is optional on read, so a
+// record carrying only `{ alive: true }` still parses.
 const life_schema = z.object({ alive: z.literal(true), pinged_at: z.string().optional() })
 
 // The watcher declares itself alive. `write_stamp` unlinks first, so a fresh `--wait` cleanly replaces
@@ -221,9 +214,9 @@ function parse_pinged_at(raw: string): number | undefined {
 	return Number.isNaN(pinged_ms) ? undefined : pinged_ms
 }
 
-// Returns `false` for any absent, unreadable or un-timestamped record — both "no watcher" and "old
-// watcher that predates joshuafolkken/kit#2113" produce `false`, which is the safe direction for a
-// guard: it speaks up rather than staying silent.
+// Returns `false` for any absent, unreadable or un-timestamped record — both "no watcher" and a record
+// without `pinged_at` produce `false`, which is the safe direction for a guard: it speaks up rather
+// than staying silent.
 function is_life_fresh(target: string, threshold_ms: number): boolean {
 	const raw = stamp_file.read_stamp_text(target)
 
@@ -243,7 +236,7 @@ function is_life_fresh(target: string, threshold_ms: number): boolean {
 // **Gone means ended.** `read_stamp_text` answers `undefined` for an absent or unowned record, and the
 // only writer is the watcher itself, so absence means `josh followup` removed it — or nobody began
 // one. Either way the watcher stops, which is the fail-quiet direction: a watcher that kept running on
-// a missing record would be the lingering process joshuafolkken/kit#1821 exists to end.
+// a missing record would be the lingering process the liveness record exists to end.
 function is_life_ended(target: string): boolean {
 	return stamp_file.read_stamp_text(target) === undefined
 }

package/scripts/run/progress/run-progress-config.ts

@@ -1,17 +1,15 @@
 import { readFileSync } from 'node:fs'
 import path from 'node:path'
 import { ancestor_directories } from '#scripts/lib/ancestor-directories'
+import { json_value } from '#scripts/lib/json-value'
 import { z } from 'zod'
 import { run_progress } from './run-progress'
 
-// Where the silence interval comes from, and in what order (joshuafolkken/kit#1576).
+// Where the silence interval comes from, and in what order.
 //
-// **The setting existed and could not leave the machine.** `JOSH_PROGRESS_INTERVAL_MINUTES` is read
-// from `.env`, which is deliberately never committed — so a person who set fifteen minutes here got
-// twenty on every other machine and in every cloud session, and the guard that enforces the floor got
-// twenty with them. Reporting still happened there, at a cadence nobody asked for.
-//
-// **So the repository carries one of its own.** `josh.progress_interval_minutes` in `package.json` is
+// **The repository carries a setting of its own.** `JOSH_PROGRESS_INTERVAL_MINUTES` is read from
+// `.env`, which is never committed, so it cannot reach other machines or cloud sessions.
+// `josh.progress_interval_minutes` in `package.json` is
 // committed, is per repository rather than per toolkit, and is read through the same reader both
 // halves of the mechanism already share — the watcher before it prints, and the `early-heartbeat` row
 // before it allows an arm. A guard that could disagree with the watcher it guards is worse than no
@@ -39,9 +37,8 @@ const package_schema = z.object({
 function read_declared_minutes(directory: string): number | undefined {
 	try {
 		const raw = readFileSync(path.join(directory, PACKAGE_FILE), 'utf8')
-		const parsed = package_schema.safeParse(JSON.parse(raw))
 
-		return parsed.success ? parsed.data.josh?.progress_interval_minutes : undefined
+		return json_value.parse_with(raw, package_schema)?.josh?.progress_interval_minutes
 	} catch {
 		return undefined
 	}

package/scripts/run/progress/run-progress-read.ts

@@ -12,22 +12,22 @@ import type { ChildObservation, LaneObservation, Observations } from './run-prog
 import { run_progress_clock } from './run-progress-clock'
 
 // Everything `josh run:progress` reads: the last-report record that makes the clock a silence clock,
-// and the observations one tick puts on the line (joshuafolkken/kit#1520).
+// and the observations one tick puts on the line.
 //
 // **Every reader here is one that already exists.** The children in flight come from
 // `epic_busy.read_repository`, which is the same `in-progress` listing `epicrun` sizes its lanes
 // from — a second definition of "running" would let the progress line disagree with the loop that
 // printed the child. The pull request comes from `run_preflight`, the lanes from `lane_registry`, and
-// the transcript sample from `run_liveness.sample_output`, whose symlink-following `statSync` is the
-// whole of joshuafolkken/kit#1485; re-`stat`ing the path here would reintroduce that bug.
+// the transcript sample from `run_liveness.sample_output`, whose symlink-following `statSync` is
+// load-bearing; re-`stat`ing the path here would risk losing it.
 //
 // **The record is kept per work tree**, keyed the way `run_hold` keys its own: two lanes of one
 // repository are two runs, and one lane's report must not silence the other's clock.
 
 // The record itself — its name, its shape, and how it is read and written — lives in
 // `run-progress-clock.ts`, because the trigger-delivered rule that refuses an early heartbeat reads
-// the same record from inside a `PreToolUse` hook and cannot await the git call this file makes
-// (joshuafolkken/kit#1570). What stays here is the asynchronous way of naming the work tree.
+// the same record from inside a `PreToolUse` hook and cannot await the git call this file makes.
+// What stays here is the asynchronous way of naming the work tree.
 const { mark, parse_stamp, read_last_report } = run_progress_clock
 
 const FIRST_LOAD_AVERAGE = 0
@@ -37,7 +37,7 @@ const FIRST_LOAD_AVERAGE = 0
 // can mean "there is nothing to report", and saying so for the third would be a confident absence
 // built on a read nobody completed. **The middle one is `idle` only when no run has started** — a run
 // underway with no `in-progress` child yet is `observed` with an empty `children`, which is the
-// heartbeat this file emits before the first label appears (joshuafolkken/kit#1900).
+// heartbeat this file emits before the first label appears.
 type ObservationRead =
 	{ kind: 'idle' } | { kind: 'observed'; observations: Observations } | { kind: 'unreadable' }
 
@@ -59,13 +59,13 @@ async function stamp_target(): Promise<string> {
 }
 
 // The ambient log's path, a sibling of the report clock — the surface `josh run:progress --path` names
-// so a person can keep it open across a session cut (joshuafolkken/kit#2156).
+// so a person can keep it open across a session cut.
 async function log_target(): Promise<string> {
 	return run_progress_clock.log_path_of(await stamp_target())
 }
 
 // The watcher's liveness record, resolved through the same resolver as `stamp_target`, so the file the
-// watcher begins is the file `josh followup` removes at the merge (joshuafolkken/kit#1821).
+// watcher begins is the file `josh followup` removes at the merge.
 async function live_target(): Promise<string> {
 	return run_progress_clock.life_target_of(await worktree_git_directory())
 }
@@ -146,8 +146,7 @@ async function has_run_record(): Promise<boolean> {
 
 /**
  * Whether a run has started in this checkout, read from a mechanical record rather than from the
- * `in-progress` label — the label is exactly what is missing in the window this bridges
- * (joshuafolkken/kit#1900).
+ * `in-progress` label — the label is exactly what is missing in the window this bridges.
  *
  * A registered lane covers an `epicrun` / `backlogrun` parent whose child has not labelled yet — and
  * it is the one signal already read for the line, so it is asked first and short-circuits the git