@joshuafolkken/kit 1.1514.0 → 1.1784.0

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

@@ -0,0 +1,91 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { git_gh_issue_write } from '#scripts/gh/git-gh-issue-write'
+import { issue_comment_cli, type CommentRequest } from '#scripts/issue/issue-comment-cli'
+import { NEEDS_DECISION_LABEL } from '#scripts/issue/issue-labels'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { issue_park } from '#scripts/issue/issue-park'
+import { session_cite } from '#scripts/issue/session-cite'
+import { cli_flags } from '#scripts/lib/cli-flags'
+import { run_park } from './run-park'
+
+// `josh run:park <N> --body-file <path>` — park a lane child for a person's decision in one call: the
+// question as a comment, `needs-decision`, and the local record the `lane-park` guard reads.
+// `josh run:park <N> --clear` takes the park back off once the decision is recorded.
+//
+// **The park was two hand-typed commands, and a child could stop after either one**
+// (joshuafolkken/kit#4132). One call writes both, and only a park that has both is recorded, so the
+// guard falls silent on exactly the child that left a question behind.
+//
+// **`in-progress` and the hold are not this command's.** A parked child keeps `in-progress`, and every
+// parked ending still owes `pnpm josh run:release <N>` (`backlogrun-park.md` → "park and continue").
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const ARGV_OFFSET = 2
+const CLEAR_FLAG = '--clear'
+const USAGE = `Usage: josh run:park <issue-number> --body-file <path> | <issue-number> ${CLEAR_FLAG}`
+const CLEAR_OPTIONS = { clear: { type: 'boolean' } } as const
+
+function clear_issue(argv: ReadonlyArray<string>): string | undefined {
+	const parsed = cli_flags.arguments_of(argv, CLEAR_OPTIONS)
+
+	if (parsed === undefined) return undefined
+
+	return issue_number_shape.single_of(parsed.positionals)
+}
+
+async function park(request: CommentRequest, directory: string): Promise<number> {
+	const { issue_number, body } = request
+	const write = await issue_park.apply(issue_number, NEEDS_DECISION_LABEL, body)
+	const is_parked = write.is_labelled && write.is_commented
+	const is_recorded = is_parked && run_park.record(issue_number, directory)
+
+	console.info(
+		`park ${session_cite.issue(issue_number)} — label: ${String(write.is_labelled)} · comment: ${String(write.is_commented)} · recorded: ${String(is_recorded)}`,
+	)
+
+	return is_parked ? SUCCESS_EXIT_CODE : FAILURE_EXIT_CODE
+}
+
+// **The record goes whatever the label answers**: the decision is a person's and already made, so a
+// guard reading a stale park would only stay silent on the child's next stop.
+async function clear(issue_number: string, directory: string): Promise<number> {
+	run_park.clear(issue_number, directory)
+	const is_cleared = await git_gh_issue_write.issue_clear_label(issue_number, NEEDS_DECISION_LABEL)
+
+	console.info(`park ${session_cite.issue(issue_number)} — cleared: ${String(is_cleared)}`)
+
+	return is_cleared ? SUCCESS_EXIT_CODE : FAILURE_EXIT_CODE
+}
+
+async function run_clear(argv: ReadonlyArray<string>, directory: string): Promise<number> {
+	const issue_number = clear_issue(argv)
+
+	if (issue_number !== undefined) return await clear(issue_number, directory)
+
+	console.error(USAGE)
+
+	return FAILURE_EXIT_CODE
+}
+
+async function run(
+	argv: ReadonlyArray<string>,
+	directory: string = process.cwd(),
+): Promise<number> {
+	if (argv.includes(CLEAR_FLAG)) return await run_clear(argv, directory)
+
+	const request = issue_comment_cli.resolve_request(argv, USAGE)
+
+	return request === undefined ? FAILURE_EXIT_CODE : await park(request, directory)
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const run_park_cli = { USAGE, run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { run_park_cli }

package/scripts/run/park/run-park.ts

@@ -0,0 +1,88 @@
+import { backlog_budget } from '#scripts/backlog/backlog-budget'
+import { git_common_directory } from '#scripts/git/git-common-directory'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { stamp_record, type StampRecordSpec } from '#scripts/josh/stamp-record'
+import { json_value } from '#scripts/lib/json-value'
+import { z } from 'zod'
+
+// The local record of a lane child's park — the half of `run:park` a `PreToolUse` guard can read.
+//
+// **The park itself is a GitHub label, which a synchronous guard cannot read**, so `lane-park` used to
+// fire on every lane-child stop, parked or not (joshuafolkken/kit#4132). `run:park` writes this record
+// once the comment and the label are both on the issue, and the guard reads it back synchronously, the
+// way the pre-gate cut guard reads `run-cut.ts`'s record.
+//
+// **Keyed to the repository and the issue, not the work tree.** The child parks from its lane, and the
+// parent clears the park from the main checkout once a person has decided; both resolve the same
+// common git directory, so `run:park --clear` removes the record wherever it runs.
+//
+// **Bounded like the cut record, and taken back by the next dispatch.** The guard asks within the run
+// that parked, seconds after the park; a label a person removed by hand, without `--clear`, must not
+// leave the guard silent on that issue's next dispatch, so `lane:dispatch` clears the record before it
+// starts the child, and a record past the lane child's idle bound reads as no park.
+
+const PARK_PREFIX = 'josh-run-park-'
+const PARK_MAX_AGE_MS = backlog_budget.DEFAULT_IDLE_MS
+
+const run_park_schema = z.object({
+	issue: z.string(),
+	parked_at: z.string(),
+})
+
+type RunPark = z.infer<typeof run_park_schema>
+
+function parse_park(raw: string): RunPark | undefined {
+	return json_value.parse_with(raw, run_park_schema)
+}
+
+function parked_at_of(park: RunPark): string {
+	return park.parked_at
+}
+
+const PARK_SPEC: StampRecordSpec<RunPark> = {
+	parse: parse_park,
+	timestamp_of: parked_at_of,
+	max_age_ms: PARK_MAX_AGE_MS,
+}
+
+function park_path(repository: string, issue: string): string {
+	return stamp_file.stamp_path(`${PARK_PREFIX}${issue}-`, repository)
+}
+
+// **The directory is injectable so a test never writes the live record** — the same reason
+// `run_cut.carried_cut_sync` takes one.
+function record(issue: string, directory: string, now: Date = new Date()): boolean {
+	const repository = git_common_directory.repository(directory)
+
+	if (repository === undefined) return false
+
+	stamp_file.replace_stamp(park_path(repository, issue), { issue, parked_at: now.toISOString() })
+
+	return true
+}
+
+function clear(issue: string, directory: string): void {
+	const repository = git_common_directory.repository(directory)
+
+	if (repository !== undefined) stamp_file.remove_stamp(park_path(repository, issue))
+}
+
+// **A fault reads as "not parked"**, the direction `carried_cut_sync` takes: the guard then speaks once,
+// which a child answers by reissuing, rather than falling silent on a run that never parked.
+function is_parked_sync(issue: string, directory: string, now: Date = new Date()): boolean {
+	const repository = git_common_directory.repository(directory)
+
+	if (repository === undefined) return false
+
+	const read = stamp_record.classify(
+		stamp_file.read_stamp_text(park_path(repository, issue)),
+		PARK_SPEC,
+		now,
+	)
+
+	return read.kind === 'carried' && read.record.issue === issue
+}
+
+const run_park = { PARK_MAX_AGE_MS, clear, is_parked_sync, record }
+
+export { run_park }

package/scripts/run/park/run-stalled.ts

@@ -0,0 +1,68 @@
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { RUN_STALLED_LABEL } from '#scripts/issue/issue-labels'
+
+// What a `run:stalled` park says, written and read in one place (joshuafolkken/kit#4215): the park
+// event carries the cause's short name after the label, the park comment its whole `Why:`, and the
+// park comments, `backlog:plan --waves` and `run:board` name the one next action.
+
+// Why a child was parked: `short` rides on the park event and the board row, `why` on the comment.
+interface StallCause {
+	short: string
+	why: string
+}
+
+// What `run:merge` judged when it parks a child with no ship stop to name.
+const SESSION_UNFINISHED: StallCause = {
+	short: 'session unfinished',
+	why: 'the child’s session ended with its issue still open and unfinished.',
+}
+const CUT_NOT_RELAUNCHED: StallCause = {
+	short: 'cut not relaunched',
+	why: 'its lane held a declared cut, but no successor could be relaunched from it (or it already was once).',
+}
+
+const RESUME_COMMAND = 'fullrun'
+const CAUSE_LEAD = `${RUN_STALLED_LABEL}: `
+const NEXT_ARROW = ' → '
+
+function resume_of(child: number | string): string {
+	return `${RESUME_COMMAND} ${issue_cite.plain(child)}`
+}
+
+// The next action as a clause, which a park comment's `Next:` and the plan's note end with.
+function next_step(child: number | string): string {
+	return `fix the cause, then resume it with \`${resume_of(child)}\` or remove \`${RUN_STALLED_LABEL}\` to offer it again`
+}
+
+function park_event(child: number | string, cause: string): string {
+	return `${issue_cite.plain(child)} parked (${CAUSE_LEAD}${cause})`
+}
+
+// The cause a park event's reason carries: `''` for a bare `run:stalled` (written before the event
+// carried one), `undefined` for a reason that is no `run:stalled` park.
+function cause_of(reason: string): string | undefined {
+	if (reason === RUN_STALLED_LABEL) return ''
+
+	return reason.startsWith(CAUSE_LEAD) ? reason.slice(CAUSE_LEAD.length) : undefined
+}
+
+// A stalled row's right end: its cause, then the action that resumes it — the action alone where no
+// cause was recorded.
+function row_text(child: number | string, cause = ''): string {
+	const resume = resume_of(child)
+
+	return cause === '' ? resume : `${cause}${NEXT_ARROW}${resume}`
+}
+
+const run_stalled = {
+	CUT_NOT_RELAUNCHED,
+	SESSION_UNFINISHED,
+	cause_of,
+	next_step,
+	park_event,
+	resume_of,
+	row_text,
+}
+
+export { run_stalled }
+export type { StallCause }

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

@@ -0,0 +1,73 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { cli_flags } from '#scripts/lib/cli-flags'
+import { run_pause, type PauseRequest, type PauseResult, type StepReport } from './run-pause'
+
+// `josh run:pause <M> --for <N>` — the argument parsing and the report around `run-pause.ts`. One
+// line per step that landed; a failure names its step, what was already done, and the rerun that
+// continues from there.
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const ARGV_OFFSET = 2
+const USAGE = 'Usage: josh run:pause <issue> --for <prerequisite>'
+const OPTIONS = { for: { type: 'string' } } as const
+
+// The prerequisite has to be another issue: `#M` blocked by itself is no order at all.
+function prerequisite_of(value: string | undefined, issue: string): string | undefined {
+	if (value === undefined || value === issue) return undefined
+
+	return issue_number_shape.is_issue_number(value) ? value : undefined
+}
+
+function parse_request(argv: ReadonlyArray<string>): PauseRequest | undefined {
+	const parsed = cli_flags.arguments_of(argv, OPTIONS)
+	if (parsed === undefined) return undefined
+	const issue = issue_number_shape.single_of(parsed.positionals)
+	const prerequisite = issue === undefined ? undefined : prerequisite_of(parsed.values.for, issue)
+
+	return issue === undefined || prerequisite === undefined ? undefined : { issue, prerequisite }
+}
+
+function report_done(done: ReadonlyArray<StepReport>): void {
+	for (const { step, detail } of done) console.info(`${step}: ${detail}`)
+}
+
+function report_failure(request: PauseRequest, result: PauseResult & { kind: 'failed' }): void {
+	const steps = result.done.map(({ step }) => step).join(', ')
+
+	console.error(`✖ ${result.step} failed: ${result.reason}`)
+	console.error(`Done: ${steps.length === 0 ? 'nothing' : steps}.`)
+	console.error(
+		`Rerun \`pnpm josh run:pause ${request.issue} --for ${request.prerequisite}\` to continue from ${result.step}.`,
+	)
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const request = parse_request(argv)
+
+	if (request === undefined) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const result = await run_pause.pause(request)
+
+	report_done(result.done)
+	if (result.kind === 'paused') return SUCCESS_EXIT_CODE
+	report_failure(request, result)
+
+	return FAILURE_EXIT_CODE
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const run_pause_cli = { USAGE, run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { run_pause_cli }

package/scripts/run/pause/run-pause.ts

@@ -0,0 +1,251 @@
+import { epic_add } from '#scripts/epic/epic-add'
+import { epic_bundle_gaps } from '#scripts/epic/epic-bundle-gaps'
+import { epic_index } from '#scripts/epic/epic-index'
+import { epic_reconcile } from '#scripts/epic/epic-reconcile'
+import { git_gh_issue_read } from '#scripts/gh/git-gh-issue-read'
+import { git_gh_issue_write } from '#scripts/gh/git-gh-issue-write'
+import { parse_json_array_or_undefined } from '#scripts/git/parse-json-array'
+import { git_stash } from '#scripts/git/stash/git-stash'
+import { stash_push_cli } from '#scripts/git/stash/stash-push-cli'
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { session_cite } from '#scripts/issue/session-cite'
+import { error_text } from '#scripts/lib/error-message'
+import { run_hold_cli } from '#scripts/run/hold/run-hold-cli'
+import { z } from 'zod'
+
+// `josh run:pause <M> --for <N>` — set a run aside while its prerequisite `#N` lands first
+// (`prerequisite.md`): the work in progress stashed under a fixed name, a comment on `#M` naming the
+// pop, `#M` blocked by `#N` and the hold released, in that order.
+//
+// **Every step asks whether it is already done before it acts**, so a rerun after a failure carries on
+// from the step that failed rather than stashing, commenting or recording twice. The state lives where
+// each write lands — the stash stack, the Issue's comments and its `blocked_by` relations — so no
+// record of its own is kept. Each write is the existing command's implementation, not a copy of it.
+
+// `epic:bundle`'s own listing limit, so both commands see the same epics.
+const EPIC_LIMIT = 200
+const SUCCESS_EXIT_CODE = 0
+const ALREADY = 'already'
+const comment_schema = z.object({ body: z.string().nullish() })
+
+interface PauseRequest {
+	issue: string
+	prerequisite: string
+}
+
+type StepName = 'stash' | 'comment' | 'blocked-by' | 'release'
+
+interface StepReport {
+	step: StepName
+	detail: string
+}
+
+type PauseResult =
+	| { kind: 'paused'; done: ReadonlyArray<StepReport> }
+	| { kind: 'failed'; step: StepName; reason: string; done: ReadonlyArray<StepReport> }
+
+function stash_message(request: PauseRequest): string {
+	return `run:pause: ${issue_cite.plain(request.issue)} waits on ${issue_cite.plain(request.prerequisite)}`
+}
+
+function comment_marker(request: PauseRequest): string {
+	return `<!-- josh:run-pause ${issue_cite.plain(request.issue)} for ${issue_cite.plain(request.prerequisite)} -->`
+}
+
+async function is_stashed(request: PauseRequest): Promise<boolean> {
+	return git_stash.select(await git_stash.list(), stash_message(request)).kind !== 'none'
+}
+
+async function stash_step(request: PauseRequest): Promise<string> {
+	if (await is_stashed(request)) return ALREADY
+
+	return await stash_push_cli.set_aside({ message: stash_message(request), dir: undefined })
+}
+
+function pause_comment(request: PauseRequest, is_work_stashed: boolean): string {
+	const work = is_work_stashed
+		? `- The work in progress was stashed. After \`pnpm josh ms\`, recover it with \`pnpm josh stash:pop "${stash_message(request)}"\` (expect conflicts).`
+		: '- The tree held no uncommitted work, so nothing was stashed.'
+
+	return [
+		`Paused: ${issue_cite.plain(request.prerequisite)} has to land first.`,
+		work,
+		comment_marker(request),
+	].join('\n')
+}
+
+async function has_pause_comment(request: PauseRequest): Promise<boolean> {
+	const json = await git_gh_issue_read.issue_list_comments(request.issue)
+	const rows = json === undefined ? undefined : parse_json_array_or_undefined(json, comment_schema)
+
+	if (rows === undefined) {
+		throw new Error(`the comments on ${session_cite.issue(request.issue)} could not be read`)
+	}
+
+	return rows.some((row) => row.body?.includes(comment_marker(request)) === true)
+}
+
+async function comment_step(request: PauseRequest): Promise<string> {
+	if (await has_pause_comment(request)) return ALREADY
+
+	const body = pause_comment(request, await is_stashed(request))
+
+	return await git_gh_issue_write.issue_comment(request.issue, body)
+}
+
+async function is_blocked(request: PauseRequest): Promise<boolean> {
+	const blockers = await git_gh_issue_read.issue_blocked_by_numbers(request.issue)
+
+	return blockers.includes(Number(request.prerequisite))
+}
+
+interface Tracking {
+	epic: number
+	// Whether the same epic already tracks the prerequisite as a row of its own.
+	is_prerequisite_child: boolean
+}
+
+// Every epic listing the child, not the one `build_epic_index` keeps: a child a second epic also
+// lists is still a row of this one.
+function is_listed_by(
+	epics: ReadonlyArray<{ number: number; body: string }>,
+	child: string,
+	epic: number,
+): boolean {
+	return epic_index.build_tracking_index(epics).get(Number(child))?.includes(epic) === true
+}
+
+// A listing cut short is no answer about absence: an epic past the cut tracks `#M` invisibly, and a
+// direct relation written then leaves that epic recording an order its body never declares.
+async function tracking_epic(request: PauseRequest): Promise<Tracking | undefined> {
+	const fetched = await epic_index.fetch_epics(EPIC_LIMIT)
+	if (fetched === undefined) throw new Error('the open epics could not be read')
+	const index = epic_index.build_epic_index(fetched.epics)
+	const epic = index.get(Number(request.issue))
+
+	if (epic === undefined && !epic_bundle_gaps.is_membership_established(fetched.cutoff)) {
+		throw new Error('the open epics were not read in full, so an epic tracking it may be unseen')
+	}
+
+	if (epic === undefined) return undefined
+
+	return { epic, is_prerequisite_child: is_listed_by(fetched.epics, request.prerequisite, epic) }
+}
+
+async function add_to_epic(epic: number, request: PauseRequest): Promise<void> {
+	const code = await epic_add.add_children({
+		epic_number: epic,
+		children: [Number(request.prerequisite)],
+		position: { kind: 'before', target: Number(request.issue) },
+	})
+
+	if (code !== SUCCESS_EXIT_CODE) {
+		throw new Error(`\`epic --add\` into ${session_cite.issue(epic)} failed`)
+	}
+}
+
+async function record_relation(request: PauseRequest): Promise<void> {
+	if (await git_gh_issue_write.issue_add_blocked_by(request.issue, request.prerequisite)) return
+
+	throw new Error('the blocked-by relation was not recorded')
+}
+
+async function refuse_unreconcilable(epic: number, request: PauseRequest): Promise<void> {
+	const link = { blocker: Number(request.prerequisite), blocked: Number(request.issue) }
+	const refusal = await epic_reconcile.refusal_after(epic, link)
+	if (refusal === undefined) return
+
+	throw new Error(
+		`\`pnpm josh epic --reconcile ${String(epic)}\` would refuse the relation, so none was recorded: ${refusal}`,
+	)
+}
+
+async function reconcile_epic(epic: number): Promise<void> {
+	if ((await epic_reconcile.reconcile_epic(epic)) === SUCCESS_EXIT_CODE) return
+
+	throw new Error(
+		`the relation was recorded, but \`pnpm josh epic --reconcile ${String(epic)}\` failed to declare it`,
+	)
+}
+
+// A prerequisite outside the epic gains its row, declaration and relation from `epic --add --before`.
+// One the epic already tracks does not: `epic --add` reads it as a move and drops every order it
+// already had, where a pause only adds one — so the relation is recorded directly and
+// `epic --reconcile` copies it into the declaration beside the others, once a dry plan shows the
+// reconcile accepts it: a refusal after the write would leave the relation undeclared. `epic --add`
+// exits 0 on a relation it failed to post, so the relation is read back after the insertion.
+async function record_in_epic(tracking: Tracking, request: PauseRequest): Promise<string> {
+	if (tracking.is_prerequisite_child) {
+		await refuse_unreconcilable(tracking.epic, request)
+		await record_relation(request)
+		await reconcile_epic(tracking.epic)
+	} else {
+		await add_to_epic(tracking.epic, request)
+		if (!(await is_blocked(request))) await record_relation(request)
+	}
+
+	return `recorded in epic ${session_cite.issue(tracking.epic)}`
+}
+
+// A relation recorded inside an epic tracking both issues is only done once it is declared, so a
+// rerun past a failed reconcile reconciles again — a no-op on an epic that already declares it.
+async function settle_recorded(request: PauseRequest): Promise<string> {
+	const tracking = await tracking_epic(request)
+	if (tracking?.is_prerequisite_child === true) await reconcile_epic(tracking.epic)
+
+	return ALREADY
+}
+
+async function blocked_by_step(request: PauseRequest): Promise<string> {
+	if (await is_blocked(request)) return await settle_recorded(request)
+
+	const tracking = await tracking_epic(request)
+	if (tracking !== undefined) return await record_in_epic(tracking, request)
+	await record_relation(request)
+
+	return 'recorded'
+}
+
+// Releasing a free record is a success, so a rerun past this step answers `released` again.
+async function release_step(request: PauseRequest): Promise<string> {
+	const code = await run_hold_cli.run(['--release', request.issue])
+	if (code !== SUCCESS_EXIT_CODE) throw new Error('`run:release` refused')
+
+	return 'released'
+}
+
+const STEPS: ReadonlyArray<[StepName, (request: PauseRequest) => Promise<string>]> = [
+	['stash', stash_step],
+	['comment', comment_step],
+	['blocked-by', blocked_by_step],
+	['release', release_step],
+]
+
+async function attempt(
+	act: (request: PauseRequest) => Promise<string>,
+	request: PauseRequest,
+): Promise<{ detail: string } | { reason: string }> {
+	try {
+		return { detail: await act(request) }
+	} catch (error) {
+		return { reason: error_text.message_of(error) }
+	}
+}
+
+async function pause(request: PauseRequest): Promise<PauseResult> {
+	const done: Array<StepReport> = []
+
+	for (const [step, act] of STEPS) {
+		// eslint-disable-next-line no-await-in-loop -- each step runs only once the one before it landed
+		const outcome = await attempt(act, request)
+		if ('reason' in outcome) return { kind: 'failed', step, reason: outcome.reason, done }
+		done.push({ step, detail: outcome.detail })
+	}
+
+	return { kind: 'paused', done }
+}
+
+const run_pause = { pause }
+
+export type { PauseRequest, PauseResult, StepReport }
+export { run_pause }

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

@@ -1,11 +1,10 @@
-#!/usr/bin/env tsx
 import { setTimeout as sleep } from 'node:timers/promises'
-import { fileURLToPath } from 'node:url'
 import { backlog_arrival, type ArrivalProbe } from '#scripts/backlog/backlog-arrival'
 import { backlog_ready } from '#scripts/backlog/backlog-ready'
 import { gh_spawn } from '#scripts/gh/gh-spawn'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
 import { error_text } from '#scripts/lib/error-message'
+import { MS_PER_SECOND } from '#scripts/lib/timeouts'
 import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
 import { run_progress, type ProgressState } from './run-progress'
 import { run_progress_args, type ParsedValues } from './run-progress-args'
@@ -34,7 +33,6 @@ import { run_progress_read, type ObservationRead } from './run-progress-read'
 
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
-const ARGV_OFFSET = 2
 // How often the loop wakes to look at the clock — not how often it reports. It is short relative to
 // the interval so that a `--mark` written by the run is noticed promptly, and long enough that a
 // watcher left running overnight costs nothing measurable.
@@ -78,7 +76,7 @@ const WAIT_EXPIRED_NOTICE = `The watch bound (\`--hours\`, ${String(DEFAULT_WAIT
 // 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
+const REPO_LOOKUP_TIMEOUT_MS = REPO_LOOKUP_TIMEOUT_SECONDS * 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 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.`
@@ -215,7 +213,7 @@ async function emit(options: WatchOptions, context: EmitContext): Promise<EmitRe
 function decline(loop: WatchLoop, now_ms: number, notice: string): WatchLoop {
 	if (loop.said !== notice) console.error(notice)
 
-	const cooldown_ms = DECLINE_RETRY_SECONDS * run_progress.MS_PER_SECOND
+	const cooldown_ms = DECLINE_RETRY_SECONDS * MS_PER_SECOND
 
 	return { ...loop, retry_at_ms: now_ms + cooldown_ms, said: notice }
 }
@@ -442,7 +440,7 @@ function to_options(values: ParsedValues): WatchOptions | undefined {
 		max_ms: run_progress_args.to_max_ms(values.hours, values.wait === true),
 		output_paths: values.output ?? [],
 		repo,
-		tick_ms: TICK_SECONDS * run_progress.MS_PER_SECOND,
+		tick_ms: TICK_SECONDS * MS_PER_SECOND,
 	}
 }
 
@@ -480,10 +478,6 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 	return await run_watch(values)
 }
 
-async function main(argv: ReadonlyArray<string>): Promise<void> {
-	process.exitCode = await run(argv)
-}
-
 const run_progress_cli = {
 	DECLINE_RETRY_SECONDS,
 	DEFAULT_WAIT_MAX_HOURS,
@@ -503,7 +497,5 @@ const run_progress_cli = {
 	wait_once,
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
-
 export type { WatchLoop, WatchOptions }
 export { run_progress_cli }

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

@@ -2,6 +2,7 @@ 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 { MS_PER_MINUTE } from '#scripts/lib/timeouts'
 import { z } from 'zod'
 
 // The report clock `josh run:progress` keeps, in the one form both of its readers can use.
@@ -48,7 +49,6 @@ const LOG_SUFFIX = '.log'
 // A few hours of heartbeats at the twenty-minute interval — enough to read the run's recent shape, and
 // bounded so an unattended run cannot grow the file without limit.
 const LOG_KEEP = 12
-const MS_PER_MINUTE = 60_000
 // Longer than any heartbeat interval and shorter than any gap between two runs. Heartbeats land at most
 // one interval apart while a run is live (twenty minutes by default, well under this), so a newest block
 // older than this belongs to a previous run: past it the log is reset rather than extended, and a fresh