@joshuafolkken/kit 1.1514.0 → 1.2114.0

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

@@ -1,12 +1,17 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
+import { cost_cli } from '#scripts/cost-runtime/cost-cli'
 import { git_followup_pending } from '#scripts/followup/git-followup-pending'
+import { session_cite } from '#scripts/issue/session-cite'
+import { telegram_notify } from '#scripts/notify/telegram-notify'
 import { release_scope_cli } from '#scripts/release/release-scope-cli'
-import { run_carry } from '#scripts/run/carry/run-carry'
+import { report_labels } from '#scripts/report/report-labels'
+import { run_carry, type CarryRead } from '#scripts/run/carry/run-carry'
 import { run_event_scope, type EventScope } from '#scripts/run/event/run-event-scope'
 import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-stream'
 import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
 import { run_report } from './run-report'
+import { run_report_handoff, type Handoff } from './run-report-handoff'
 
 // `josh run:report` — the session-facing report, generated from the run's event stream rather than
 // composed by hand. It reads the events the run appended, asks `release:scope`
@@ -18,8 +23,23 @@ import { run_report } from './run-report'
 // **The body it prints is the Telegram body too.** `josh notify --body-file <file>` sends exactly this
 // output, so the summary a session shows and the message a person reads off-screen are one string from one
 // generator, never a second wording of the same facts.
+//
+// `--handoff` prints the `backlogrun` hand-off report (`run-report-handoff.ts`) from the same reads —
+// the run record and the scoped stream — and sends it itself as the `confirmation`, the resume command
+// as its `recommended` choice (joshuafolkken/kit#4161). The body is built with plain `#N` and linked
+// here, at the print boundary, through `session_cite.text`.
 
+const ARGV_OFFSET = 2
 const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const HANDOFF_FLAG = '--handoff'
+const USAGE = `Usage: josh run:report [${HANDOFF_FLAG}]`
+const NO_RECORD_NOTE =
+	'No readable run record, so there is no run to hand off. Begin one with `pnpm josh run:carry --begin` first.'
+const HANDOFF_TITLE = 'backlogrun hand-off'
+const HANDOFF_RECOVERY = 'If this did not arrive, the session transcript holds the same report.'
+const NO_RESUME_NOTE =
+	'The run record names no resume command, so no hand-off confirmation was sent; the report above is the hand-off.'
 
 // An absent or unreadable stream is an empty run, the same fail-quiet direction the stream's own reader
 // takes — a report with no events is a report, not an error.
@@ -31,40 +51,108 @@ async function read_stream(): Promise<ReadonlyArray<RunEvent>> {
 	return run_event_stream.read_events(target)
 }
 
+// The run record this checkout holds, or `undefined` when the git directory cannot be resolved.
+async function read_record(): Promise<CarryRead | undefined> {
+	const directory = await run_carry.repository_directory()
+
+	if (directory === undefined) return undefined
+
+	return run_carry.read_carry(run_carry.carry_path(directory))
+}
+
 // The invocation this report covers, taken from the run record that already holds the start time.
 // A checkout whose git directory cannot be resolved has no record to read, which is the same
 // undetermined answer an absent record gives — and neither one falls back to the whole stream.
-async function read_scope(): Promise<EventScope> {
-	const directory = await run_carry.repository_directory()
+function scope_of(read: CarryRead | undefined): EventScope {
+	if (read === undefined) return run_event_scope.UNKNOWN_EVENT_SCOPE
 
-	if (directory === undefined) return run_event_scope.UNKNOWN_EVENT_SCOPE
-
-	return run_event_scope.scope_of(run_carry.read_carry(run_carry.carry_path(directory)))
+	return run_event_scope.scope_of(read)
 }
 
 // The three reads are independent, so they are issued together rather than one after another — the stream, the
 // pending-merge count and the run record share no input.
-async function run(): Promise<number> {
-	const [events, pending, scope] = await Promise.all([
+async function run_summary(): Promise<number> {
+	const [events, pending, read] = await Promise.all([
 		read_stream(),
 		git_followup_pending.read_pending({}),
-		read_scope(),
+		read_record(),
 	])
 	const release = release_scope_cli.decide(pending)
 
-	process.stdout.write(`${run_report.build_report({ events, release, scope })}\n`)
+	process.stdout.write(`${run_report.build_report({ events, release, scope: scope_of(read) })}\n`)
 
 	return SUCCESS_EXIT_CODE
 }
 
-async function main(): Promise<void> {
-	process.exitCode = await run()
+type CarriedRead = Extract<CarryRead, { kind: 'carried' }>
+
+// The report is the hand-off, so it succeeds once printed. The send is `confirm`'s tolerant one, which
+// already reports its own failure with `HANDOFF_RECOVERY` — a checkout with no Telegram credentials is
+// one, and pointing it at `josh notify` would fail the same way. A record whose invocation names no
+// resume command has no `recommended` to send.
+async function send_handoff(handoff: Handoff): Promise<void> {
+	if (handoff.resume === undefined) {
+		console.error(NO_RESUME_NOTE)
+
+		return
+	}
+
+	await telegram_notify.confirm({
+		issue_title: HANDOFF_TITLE,
+		body: handoff.body,
+		recovery: HANDOFF_RECOVERY,
+		recommended: handoff.resume,
+		alternatives: [],
+	})
+}
+
+function handoff_of(read: CarriedRead, events: ReadonlyArray<RunEvent>): Handoff {
+	return run_report_handoff.build_handoff({
+		carry: read.carry,
+		events: run_event_scope.scoped_events(events, scope_of(read)) ?? [],
+		figures: cost_cli.session_figures(),
+		labels: report_labels.session_labels(),
+	})
+}
+
+async function run_handoff(): Promise<number> {
+	const [events, read] = await Promise.all([read_stream(), read_record()])
+
+	if (read?.kind !== 'carried') {
+		console.error(NO_RECORD_NOTE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const built = handoff_of(read, events)
+	const handoff = { ...built, body: session_cite.text(built.body) }
+
+	process.stdout.write(`${handoff.body}\n`)
+	await send_handoff(handoff)
+
+	return SUCCESS_EXIT_CODE
+}
+
+async function run(argv: ReadonlyArray<string> = []): Promise<number> {
+	if (argv.length === 0) return await run_summary()
+	if (argv.length === 1 && argv[0] === HANDOFF_FLAG) return await run_handoff()
+
+	console.error(USAGE)
+
+	return FAILURE_EXIT_CODE
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
 }
 
 const run_report_cli = {
+	NO_RECORD_NOTE,
+	NO_RESUME_NOTE,
+	USAGE,
 	run,
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main()
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
 
 export { run_report_cli }

package/scripts/run/run-report-handoff.ts

@@ -0,0 +1,114 @@
+import { backlog_drive_restore } from '#scripts/backlog/backlog-drive-restore'
+import type { SessionFigures } from '#scripts/cost-runtime/cost-cli'
+import { issue_cite } from '#scripts/issue/issue-cite'
+import type { HandoffLabels, ReportLabels } from '#scripts/report/report-labels'
+import { run_carry, type RunCarry } from '#scripts/run/carry/run-carry'
+import type { RunEvent } from '#scripts/run/event/run-event-stream'
+import { run_invocation } from '#scripts/run/run-invocation'
+
+// `josh run:report --handoff` — the report a `backlogrun` writes when it hands the rest of a batch to a
+// new session, generated from the values that already answer each line rather than filled in by hand:
+// the run record (`run:carry`) names what merged, what is left and the command that resumes the run,
+// the invocation's events name what parked, and `cost --cut`'s figures name why it stopped. **The
+// hand-off is a fourth kind of stop**, so it carries the hand-off labels and never the completion
+// report's `cause` / `fix` / `result` — an unfinished epic would read as finished.
+//
+// **The body is the Telegram body too**, as `run:report`'s is: the CLI prints it and sends it as the
+// `confirmation`, the resume command as its `recommended` choice.
+
+const LINE_SEPARATOR = '\n'
+const LIST_SEPARATOR = ', '
+const COST_COMMAND = '`pnpm josh cost --cut`'
+
+interface HandoffInput {
+	carry: RunCarry
+	// This invocation's events, already scoped by `run-event-scope.ts`.
+	events: ReadonlyArray<RunEvent>
+	figures: SessionFigures
+	labels: ReportLabels
+}
+
+interface Handoff {
+	body: string
+	// The command that resumes the run, or `undefined` for a record whose invocation does not parse.
+	resume: string | undefined
+}
+
+function issue_list(issues: ReadonlyArray<number>, labels: HandoffLabels): string {
+	if (issues.length === 0) return labels.none
+
+	return issues.map((issue) => issue_cite.plain(issue)).join(LIST_SEPARATOR)
+}
+
+// The children that parked in this invocation and never merged — named apart from the remaining list,
+// because a parked child is settled for this run but is not done.
+function parked_of(input: HandoffInput): ReadonlyArray<number> {
+	const merged = input.carry.merged_issues ?? []
+
+	return [...backlog_drive_restore.parked_issues(input.events)].filter(
+		(issue) => !merged.includes(issue),
+	)
+}
+
+// **Never omitted**: it is the one line that tells this report from a completion report. A budget-only
+// invocation named no list, so what is left is the pool rather than a count.
+function remaining_line(input: HandoffInput, remaining: ReadonlyArray<number> | undefined): string {
+	const labels = input.labels.handoff
+	const parked = parked_of(input)
+	const listed = remaining === undefined ? labels.pool : issue_list(remaining, labels)
+	const count = remaining === undefined ? '' : ` (${String(remaining.length)})`
+	const parked_note =
+		parked.length === 0 ? '' : ` · ${labels.parked}: ${issue_list(parked, labels)}`
+
+	return `${listed}${count}${parked_note}`
+}
+
+// An unmeasurable session quotes its verdict where the cost would be, never a `0`.
+function measurement_line(figures: SessionFigures): string {
+	const cost = figures.cost === undefined ? figures.verdict : String(figures.cost)
+
+	return `${cost} / ${String(figures.threshold)}`
+}
+
+function command_line(resume: string | undefined, labels: HandoffLabels): string {
+	return resume === undefined ? labels.none : `\`${resume}\``
+}
+
+function body_lines(
+	input: HandoffInput,
+	handoff_resume: string | undefined,
+): ReadonlyArray<string> {
+	const labels = input.labels.handoff
+	const remaining = run_carry.remaining_of(input.carry)
+
+	return [
+		`**${labels.title}**`,
+		'',
+		`- **${labels.done}**: ${issue_list(input.carry.merged_issues ?? [], labels)}`,
+		`- **${labels.remaining}**: ${remaining_line(input, remaining)}`,
+		`- **${labels.why_stopped}**: ${COST_COMMAND} → ${input.figures.verdict}`,
+		`- **${labels.next_command}**: ${command_line(handoff_resume, labels)}`,
+		'',
+		`**${input.labels.details}**`,
+		'',
+		`- ${labels.measurement}: ${measurement_line(input.figures)}`,
+		`- ${labels.handover}: ${labels.handover_text}`,
+	]
+}
+
+// Handed the same record, events and figures it returns the same report — nothing here reads a clock,
+// the environment or the network, which is what the tests pin. The resume command is the record's own
+// invocation: `run:carry` resumes a record only when the invocation matches it exactly, so a command
+// shrunk to the remaining issues would be refused and its recovery would drop the carried counts.
+function build_handoff(input: HandoffInput): Handoff {
+	const resume = run_invocation.rebuild(input.carry.invocation)
+
+	return { body: body_lines(input, resume).join(LINE_SEPARATOR), resume }
+}
+
+const run_report_handoff = {
+	build_handoff,
+}
+
+export type { Handoff, HandoffInput }
+export { run_report_handoff }

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

@@ -1,4 +1,4 @@
-import { has_label_name, PLANNED_LABEL } from '#scripts/issue/issue-labels'
+import { issue_state } from '#scripts/issue/issue-state'
 import { issue_state_cli, type StateRead } from '#scripts/issue/issue-state-cli'
 import { run_halfrun_resume } from './run-halfrun-resume'
 import { run_prrun_resume, type PrrunToken } from './run-prrun-resume'
@@ -23,10 +23,6 @@ function is_closed(read: StateRead): boolean {
 	return read.kind === 'state' && read.state.state === CLOSED
 }
 
-function is_planned(read: StateRead): boolean {
-	return read.kind === 'state' && has_label_name(read.state.labels, PLANNED_LABEL)
-}
-
 // The two stops are one hold record, so at most one is present; the `prrun` one is asked only when the
 // `halfrun` one is not, which spares its pull-request read.
 async function read_stop(
@@ -50,7 +46,7 @@ async function read_stage(issue: string): Promise<StageRead> {
 		is_closed: is_closed(issue_read),
 		is_prrun_stopped: stop.prrun_token !== undefined,
 		is_halfrun_stopped: stop.is_halfrun_stopped,
-		is_planned: is_planned(issue_read),
+		is_planned: issue_state.is_planned(issue_read),
 	})
 
 	return { state, prrun_token: stop.prrun_token }

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

@@ -14,6 +14,7 @@ import { run_prep, type PrepParts } from './run-prep'
 import { run_prep_cli } from './run-prep-cli'
 import { run_retrospective } from './run-retrospective'
 import { run_step, type ParentInput, type StepInput } from './run-step'
+import { run_step_lane_plan } from './run-step-lane-plan'
 import { run_step_section } from './run-step-section'
 
 // `josh run:step [<N>]` — print the run's next single action, followed by the section that governs it
@@ -165,11 +166,22 @@ async function run_parent(): Promise<number> {
 	return FAILURE_EXIT_CODE
 }
 
-function report({ input, ship_problems }: Gathered): number {
+// The action line, then — under `implement` — the `lane:plan` a lane child runs before its first edit.
+// Only `implement` reads it, so no other step pays for the plan comment's request.
+async function action_lines(input: StepInput, line: string): Promise<ReadonlyArray<string>> {
+	if (line !== run_step.IMPLEMENT) return [line]
+	const next = await run_step_lane_plan.line_for(input.issue_number, input.is_lane_child)
+
+	return next === undefined ? [line] : [line, next]
+}
+
+async function report({ input, ship_problems }: Gathered): Promise<number> {
 	const action = run_step.next_action(input)
 
-	console.info(action.line)
-	// On stderr, so stdout stays the action line and its rule: what `josh ship` would
+	const lines = await action_lines(input, action.line)
+
+	for (const line of lines) console.info(line)
+	// On stderr, so stdout stays the action lines and their rule: what `josh ship` would
 	// refuse on is said at every step, while it is still cheap to meet.
 	if (ship_problems.length > 0) console.error(run_prep.ship_body(ship_problems))
 
@@ -177,7 +189,7 @@ function report({ input, ship_problems }: Gathered): number {
 	// same failure, so a position missing its issue state is never read as a confident next step.
 	if (input.state === undefined) return FAILURE_EXIT_CODE
 
-	return run_step_section.print_for(action)
+	return run_step_section.print_for(action, input.is_lane_child)
 }
 
 async function run(argv: ReadonlyArray<string>): Promise<number> {
@@ -191,7 +203,7 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 		return FAILURE_EXIT_CODE
 	}
 
-	return report(await gather(issue_number))
+	return await report(await gather(issue_number))
 }
 
 async function main(argv: ReadonlyArray<string>): Promise<void> {

package/scripts/run/run-step-lane-plan.ts

@@ -0,0 +1,27 @@
+import { backlog_plan_comment } from '#scripts/backlog/backlog-plan-comment'
+import { lane_plan } from '#scripts/lane/lane-plan'
+import { shell_quote } from '#scripts/lib/shell-quote'
+
+// The `lane:plan` command a lane child runs before its first edit — `lane-plan-guard.ts` refuses that
+// edit until the plan is cleared. joshuafolkken/kit#4910's child retried a refused Edit eight times
+// before it ran `lane:plan`, since nothing it read named the step first (joshuafolkken/kit#4923).
+// The paths are its plan comment's; with none, the child names its own.
+
+const PATH_PLACEHOLDER = '<path>...'
+
+// The command to print under `implement`, or `undefined` when not a lane child or its plan is cleared.
+async function line_for(issue_number: string, is_lane_child: boolean): Promise<string | undefined> {
+	const issue = Number(issue_number)
+
+	if (!is_lane_child || !lane_plan.is_uncleared(issue, process.cwd())) return undefined
+
+	const paths = await backlog_plan_comment.plan_paths(issue)
+	const named =
+		paths.length === 0 ? PATH_PLACEHOLDER : paths.map((path) => shell_quote.word(path)).join(' ')
+
+	return `pnpm josh lane:plan ${issue_number} ${named}`
+}
+
+const run_step_lane_plan = { line_for }
+
+export { run_step_lane_plan }

package/scripts/run/run-step-section.ts

@@ -27,7 +27,8 @@ function reference(document: string, heading: string): SectionReference {
 }
 
 // The gate's chain governs both the implementation it follows and a stopped ship's report.
-const CHAIN = reference('chain-rule.md', 'Run the review-to-merge chain')
+const CHAIN_RULE = 'chain-rule.md'
+const CHAIN = reference(CHAIN_RULE, 'Run the review-to-merge chain')
 const PROGRESS = 'backlogrun-progress.md'
 
 // Keyed on a verdict token, or on the josh subcommand a command action runs. An action with no row —
@@ -47,6 +48,17 @@ const GOVERNING_SECTIONS: ReadonlyMap<string, SectionReference> = new Map([
 	['run:carry', reference(PROGRESS, 'The hand-off')],
 ])
 
+// **A lane child reads its own step of the chain, never the whole of it** (joshuafolkken/kit#5016):
+// the chain's step 1 opens with `josh main:merge`, which a lane child leaves to ship's sync, and a
+// child handed the whole section ran it, moving the tree its scoped pair was green on. The step is
+// the chain's labelled step 0, cited where it stands, so it is written once; it ends at the sibling
+// item `1.`, so a blank line inside it would cut it short. A stopped ship's report reads it too.
+const LANE_CHILD_STEP = reference(CHAIN_RULE, 'A lane child')
+const LANE_CHILD_SECTIONS: ReadonlyMap<string, SectionReference> = new Map([
+	[run_step.IMPLEMENT, LANE_CHILD_STEP],
+	['ship', LANE_CHILD_STEP],
+])
+
 function key_of(action: StepAction): string {
 	if (action.kind !== 'command') return action.line
 
@@ -55,27 +67,34 @@ function key_of(action: StepAction): string {
 	return subcommand
 }
 
-function section_for(key: string): SectionReference | undefined {
-	return GOVERNING_SECTIONS.get(key)
+function section_for(key: string, is_lane_child: boolean): SectionReference | undefined {
+	const lane_child_section = is_lane_child ? LANE_CHILD_SECTIONS.get(key) : undefined
+
+	return lane_child_section ?? GOVERNING_SECTIONS.get(key)
 }
 
 // Printed through `doc:section` itself, so the extent, the Bash-cap split and the refusal of an
 // unresolved heading are that command's, never a second copy of them.
-function print_section(key: string, root: string = process.cwd()): number {
-	const found = section_for(key)
+function print_section(key: string, root: string = process.cwd(), is_lane_child = false): number {
+	const found = section_for(key, is_lane_child)
 
 	if (found === undefined) return SUCCESS_EXIT_CODE
 
 	return document_section_cli.run([found.document, found.heading], root)
 }
 
-function print_for(action: StepAction, root: string = process.cwd()): number {
-	return print_section(key_of(action), root)
+function print_for(
+	action: StepAction,
+	is_lane_child = false,
+	root: string = process.cwd(),
+): number {
+	return print_section(key_of(action), root, is_lane_child)
 }
 
 const run_step_section = {
 	ENTRY,
 	GOVERNING_SECTIONS,
+	LANE_CHILD_SECTIONS,
 	key_of,
 	print_for,
 	print_section,

package/scripts/run/run-step.ts

@@ -156,10 +156,13 @@ const KIND = run_event_stream.EVENT_KIND
 const OFFER_BACKLOG = 'pnpm josh backlog:next'
 const EVENT_ACTIONS: Record<string, (issue_number: string) => StepAction> = {
 	[KIND.PR_OPENED]: () => command('pnpm josh followup'),
-	[KIND.REVIEW_ROUND]: () => command('pnpm josh review:round2'),
+	[KIND.REVIEW_ROUND]: (issue_number) =>
+		command(`pnpm josh review:round2 --record ${issue_number}`),
 	[KIND.MERGE]: merge_command,
 	[KIND.OUTAGE]: merge_command,
 	[KIND.PARK]: () => command(OFFER_BACKLOG),
+	// The child was released; `backlog:drive` holds the next launch until the limit resets.
+	[KIND.USAGE_LIMIT]: () => command(OFFER_BACKLOG),
 	[KIND.CUT]: (issue_number) => command(`pnpm josh run:cut --resume ${issue_number}`),
 	// A stall is undispatched ready work with a free lane, so its next step is exactly a park's: offer
 	// the backlog. The detector only reports the stall; reading it here as a dispatch is what turns the
@@ -177,7 +180,7 @@ const EVENT_ACTIONS: Record<string, (issue_number: string) => StepAction> = {
 // budget command — a child that ran it would read the `busy` it got back as a competing session and
 // park its Issue unimplemented. A merge or an outage is the parent's to classify, so a child at one
 // has nothing to run and stops rather than being handed `run:merge`.
-const PARENT_ONLY_EVENTS: ReadonlySet<string> = new Set([KIND.MERGE, KIND.OUTAGE])
+const PARENT_ONLY_EVENTS: ReadonlySet<string> = new Set([KIND.MERGE, KIND.OUTAGE, KIND.USAGE_LIMIT])
 
 // A stopped run's last owed step is the end-of-run retrospective. When it is not owed the position stops
 // with no command to run.
@@ -271,7 +274,7 @@ function closed_action(input: StepInput): StepAction {
 
 	return {
 		kind: 'decide',
-		line: `decide: ${session_cite.issue(input.issue_number)} is closed but this tree holds uncommitted work — keep it with \`git stash push -u -m "${message}"\` | carry it into a new issue`,
+		line: `decide: ${session_cite.issue(input.issue_number)} is closed but this tree holds uncommitted work — keep it with \`pnpm josh stash:push "${message}"\` | carry it into a new issue`,
 	}
 }
 

package/scripts/run/run-stranded-detect.ts

@@ -42,6 +42,8 @@ interface DetectPorts {
 	notify_stranded: (body: string) => Promise<boolean>
 }
 
+type SameProcess = NonNullable<Parameters<typeof run_stranded.supervisor_liveness>[1]>
+
 interface RecordTargets {
 	carry: string
 	wake: string
@@ -151,6 +153,16 @@ function is_stranded_at(directory: string, ports: DetectPorts = DEFAULT_PORTS):
 	return input !== undefined && run_stranded.is_stranded(input)
 }
 
+// The default ports with both liveness probes asked through `same_process` — `run:board` hands the one
+// that reads its own `ps` snapshot (joshuafolkken/kit#4263).
+function ports_with(same_process: SameProcess): DetectPorts {
+	return {
+		...DEFAULT_PORTS,
+		is_owner_live: (carry) => run_carry.is_owner_live(carry, new Date(), same_process),
+		supervisor_liveness: (wake) => run_stranded.supervisor_liveness(wake, same_process),
+	}
+}
+
 // The judgement a supervisor asks of the run it is about to stop watching. The asker is that
 // supervisor on its way out, so it is taken as gone, and so is an owner that is the asker itself
 // (`run_carry.is_held_by_another`) — that owner is about to be gone. A
@@ -173,6 +185,7 @@ const run_stranded_detect = {
 	detect_and_report,
 	is_left_stranded,
 	is_stranded_at,
+	ports_with,
 	run_stranded_check,
 }
 

package/scripts/run/run-watcher-guard-cli.ts

@@ -9,7 +9,7 @@ import { run_watcher_guard } from './run-watcher-guard'
 // through `run-watcher-hook.ts` so every tool call is checked.
 //
 // **Exits 0 (ok) or 1 (stale).** A non-zero exit is what the hook mechanism treats as a refusal —
-// the same contract `batch:guard` and `rule:guard` hold.
+// the same contract `pretool:guard` holds.
 
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1

package/scripts/run/run-watcher-guard.ts

@@ -1,4 +1,5 @@
 import { lane_registry } from '#scripts/lane/lane-registry'
+import { MS_PER_SECOND } from '#scripts/lib/timeouts'
 import { run_progress_clock } from '#scripts/run/progress/run-progress-clock'
 import { run_headless } from './run-headless'
 
@@ -18,7 +19,6 @@ import { run_headless } from './run-headless'
 
 const WATCHER_TICK_MS = 30_000
 const TICK_MULTIPLIER = 3
-const MS_PER_SECOND = 1000
 
 const STALE_THRESHOLD_MS = WATCHER_TICK_MS * TICK_MULTIPLIER
 const STALE_THRESHOLD_S = STALE_THRESHOLD_MS / MS_PER_SECOND