@joshuafolkken/kit 1.1035.0 → 1.1094.0

package/scripts/run/run-liveness.ts

@@ -3,8 +3,8 @@ import { homedir, tmpdir } from 'node:os'
 import path from 'node:path'
 import { setTimeout as sleep } from 'node:timers/promises'
 import { agent_event, type AgentEventState } from '#scripts/agent/agent-event'
-import { git_gh_issue_read } from '#scripts/git/git-gh-issue-read'
-import { ALREADY_DONE_LABEL, NEEDS_DECISION_LABEL } from '#scripts/git/issue-labels'
+import { git_gh_issue_read } from '#scripts/gh/git-gh-issue-read'
+import { ALREADY_DONE_LABEL, NEEDS_DECISION_LABEL } from '#scripts/issue/issue-labels'
 import { issue_state } from '#scripts/issue/issue-state'
 import { PLATFORM_TEMP_ROOT } from '#scripts/josh/platform-temporary'
 import { run_hold } from './run-hold'
@@ -401,7 +401,6 @@ const run_liveness = {
 	decide,
 	describe_agent_state,
 	read_child_settled,
-	read_agent_state,
 	read_output_frozen,
 	sample_output,
 	to_safe_path,

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

@@ -5,6 +5,7 @@ import { api_outage } from '#scripts/agent/api-outage'
 import { CONTEXT_CUT_THRESHOLD } from '#scripts/cost-runtime/context-cut-threshold'
 import { issue_closing_pr } from '#scripts/issue/issue-closing-pr'
 import { issue_state_cli } from '#scripts/issue/issue-state-cli'
+import { lane_handoff } from '#scripts/lane/lane-handoff'
 import { run_carry, type CarryOwner, type RunCarry } from './run-carry'
 import { run_ending } from './run-ending'
 import { run_event_stream } from './run-event-stream'
@@ -12,8 +13,6 @@ import { run_event_stream_emit } from './run-event-stream-emit'
 import { run_issue_number } from './run-issue-number'
 import { run_merge, type ChildOutcome, type EndingSignals } from './run-merge'
 import { run_merge_steps, type MergeContext } from './run-merge-steps'
-import { run_ship_detach } from './run-ship-detach'
-import { run_ship_probe } from './run-ship-probe'
 
 // `josh run:merge <N>` — one composite command for a `backlogrun` merge event (joshuafolkken/kit#2024).
 // The parent's context is the largest and its per-turn cost the highest, and the event was two turns:
@@ -316,7 +315,10 @@ async function on_cut(ctx: MergeContext): Promise<MergeVerdict> {
 
 // A child that parked itself: nothing is counted, but the park is written to the stream as a failed
 // child's is, so a reader restoring the run from its events sees the child settled (joshuafolkken/kit#2508).
+// Its `in-progress` is dropped as a failed child's is: left on, it outlived the `needs-decision` a
+// person later lifted, and a `run:solo` child then held the whole backlog (joshuafolkken/kit#3017).
 async function on_parked(ctx: MergeContext): Promise<MergeVerdict> {
+	await run_merge_steps.remove_in_progress(ctx.child)
 	await run_event_stream_emit.emit(run_event_stream.EVENT_KIND.PARK, `#${ctx.child} parked`)
 
 	return emit(await run_merge_steps.ask_next(ctx), SUCCESS_EXIT_CODE)
@@ -355,18 +357,10 @@ const HANDLERS: Readonly<Record<ChildOutcome, (ctx: MergeContext) => Promise<Mer
 	shipping: on_shipping,
 }
 
-async function is_ship_running(child: string): Promise<boolean> {
-	const repository = await run_ship_probe.repository_directory()
-
-	return (
-		repository !== undefined && run_ship_detach.read_result(repository, child)?.result === 'running'
-	)
-}
-
 // The whole merge event for one returned child, in-process: read its state, classify it, and run the
 // handler. The CLI prints the token; `backlog:drive` branches on the outcome (joshuafolkken/kit#2508).
 async function merge_child(ctx: MergeContext): Promise<MergeResult> {
-	if (await is_ship_running(ctx.child)) {
+	if (lane_handoff.is_ship_running(ctx.child, process.cwd())) {
 		return { outcome: 'shipping', ...(await on_shipping()) }
 	}
 
@@ -405,8 +399,6 @@ const run_merge_cli = {
 	RESUMED_TOKEN,
 	RETRY_TOKEN,
 	STOP_TOKEN,
-	USAGE,
-	main,
 	merge_child,
 	parse,
 	run,

package/scripts/run/run-merge-steps.ts

@@ -1,9 +1,9 @@
 import { existsSync } from 'node:fs'
 import path from 'node:path'
-import { git_followup_issue_close } from '#scripts/git/git-followup-issue-close'
-import { git_gh_issue_write } from '#scripts/git/git-gh-issue-write'
-import { git_stash } from '#scripts/git/git-stash'
-import { IN_PROGRESS_LABEL, NEEDS_DECISION_LABEL } from '#scripts/git/issue-labels'
+import { git_followup_issue_close } from '#scripts/followup/git-followup-issue-close'
+import { git_gh_issue_write } from '#scripts/gh/git-gh-issue-write'
+import { git_stash } from '#scripts/git/stash/git-stash'
+import { IN_PROGRESS_LABEL, NEEDS_DECISION_LABEL } from '#scripts/issue/issue-labels'
 import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
 import { lane_close } from '#scripts/lane/lane-close'
 import { lane_reap } from '#scripts/lane/lane-reap'
@@ -347,7 +347,6 @@ async function ask_next(ctx: MergeContext): Promise<string> {
 
 const run_merge_steps = {
 	CUT_RELAUNCH_CAUSE,
-	apply_carry,
 	ask_next,
 	do_failed,
 	do_merged,
@@ -355,6 +354,7 @@ const run_merge_steps = {
 	has_resumable_cut,
 	is_over_budget,
 	refused_carry,
+	remove_in_progress,
 	resume_cut,
 }
 

package/scripts/run/run-merge.ts

@@ -3,7 +3,7 @@ import {
 	EPIC_LABEL,
 	has_label_name,
 	NEEDS_DECISION_LABEL,
-} from '#scripts/git/issue-labels'
+} from '#scripts/issue/issue-labels'
 import type { IssueState } from '#scripts/issue/issue-state'
 import type { CarryChange, RunCarry } from './run-carry'
 

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

@@ -41,7 +41,7 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 	process.exitCode = await run(argv)
 }
 
-const run_next_cli = { USAGE, main, run }
+const run_next_cli = { run }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
 

package/scripts/run/run-parent-cut-hook.ts

@@ -0,0 +1,143 @@
+import { CONTEXT_CUT_THRESHOLD } from '#scripts/cost-runtime/context-cut-threshold'
+import { cost_cli, type CostVerdict } from '#scripts/cost-runtime/cost-cli'
+import { cost_format } from '#scripts/cost-runtime/cost-format'
+import { cost_verdict } from '#scripts/cost-runtime/cost-verdict'
+import { hook_decision } from '#scripts/josh/hook-decision'
+import { implementation_cut_verdict } from '#scripts/rules/implementation-cut-verdict'
+import { run_carry, type RunCarry } from './run-carry'
+import { run_headless } from './run-headless'
+import { run_watcher_hook } from './run-watcher-hook'
+
+// The `backlogrun` parent's hand-off, delivered at the call it binds on (joshuafolkken/kit#2947).
+//
+// **The parent's hand-off was asked only at a merge, and the context grew between merges.** The
+// orchestrator never implements, yet on 2026-10-02 parent 259fb6d5 sent 111 of its 170 requests past
+// the shared threshold, peaking at 207,081 tokens: `pnpm josh cost --cut` is read after each child's
+// merge (`backlogrun-progress.md` → "The hand-off"), and a long wait or a lane-failure investigation
+// between two merges is exactly where it went unread. This is the lesson `implementation-cut.ts` records
+// for a lane child, one session up — a check carried as a step is taken late, a `PreToolUse` refusal is
+// taken at the next call.
+//
+// **The same statistic and the same threshold, never a second measurement.** The verdict is
+// `cost_cli.session_verdict` — what `pnpm josh cost --cut` prints — read through the implementation cut's
+// short reuse window so a burst of calls is priced once.
+//
+// **It is async and composed after the synchronous guards, like the watcher guard.** Telling the parent
+// apart reads the carry record through `run_headless.driving_carry`, which is asynchronous; reusing it is
+// what keeps a second, synchronous spelling of the parent test from existing.
+
+const SWITCH_ENV_KEY = 'JOSH_PARENT_CUT_GUARD'
+const STAMP_PREFIX = 'josh-parent-cut-guard-'
+
+// **One refusal, then a quiet window long enough to finish the hand-off in.** The hand-off is several
+// calls — `lane:list`, `lane:output`, `run:carry --cut`, `run:wake`, the progress comment — and a guard
+// refusing each of them would wedge the very procedure it asks for. A parent that could not cut (a lane
+// nobody can poll) is asked again once the window has passed, which is the "next opportunity" the merge
+// seam used to be.
+const QUIET_WINDOW_MS = 600_000
+
+// What the decision has to know about the world, passed in so it is testable without a carry record or
+// a session transcript on disk.
+interface ParentCutState {
+	carry: () => Promise<RunCarry | undefined>
+	verdict: () => CostVerdict
+}
+
+function current_state(): ParentCutState {
+	return {
+		carry: async (): Promise<RunCarry | undefined> => await run_headless.driving_carry(),
+		verdict: (): CostVerdict =>
+			implementation_cut_verdict.reused_verdict(() => cost_cli.session_verdict()),
+	}
+}
+
+const THRESHOLD_TEXT = `${cost_format.format_tokens(CONTEXT_CUT_THRESHOLD)}-token`
+
+const PARENT_CUT_REASON =
+	'⛔ backlogrun parent hand-off: this session drives a `backlogrun` (it owns the live carry record) and ' +
+	`its recent-context cost has crossed the shared ${THRESHOLD_TEXT} threshold between merges, so every ` +
+	'later request re-reads the accumulated context (joshuafolkken/kit#2947). Take the hand-off now rather ' +
+	'than at the next merge: follow `.claude/skills/workflow-commands/backlogrun-progress.md` → "The ' +
+	'hand-off" from its `over` branch — open no new lane and take no new child, read `pnpm josh lane:list`, ' +
+	'make sure every lane in flight records an output path, then run `pnpm josh run:carry --cut --owner ' +
+	'"$PPID"` and, unless it answers `capped`, `pnpm josh run:wake`, post the progress comment and end the ' +
+	'turn. A lane nobody can poll means the cut does not happen; carry on and this asks again later. ' +
+	'Reissue this call when the hand-off is done or cannot be taken — the guard stays quiet for a while ' +
+	'after it refuses, so the hand-off calls themselves are not refused.'
+
+// Neither an uncapped parent's own record nor a measured `over` is optional: a capped record has no cut
+// left to take (`run:carry --cut` answers `capped`), and an unmeasurable session is left alone here —
+// refusing every call of a session that cannot be priced would wedge it, while the merge-seam check
+// still takes `over`'s branch for it.
+async function is_due(state: ParentCutState): Promise<boolean> {
+	const carry = await state.carry()
+
+	if (carry === undefined || run_carry.is_at_cut_cap(carry)) return false
+
+	return state.verdict() === cost_verdict.OVER_VERDICT
+}
+
+function is_quiet(target: string, now_ms: number): boolean {
+	const last_ms = hook_decision.create_refusal_stamp(STAMP_PREFIX).last_ms(target)
+
+	return last_ms !== hook_decision.NEVER_MS && now_ms - last_ms < QUIET_WINDOW_MS
+}
+
+// The quiet window is read before the carry record and the transcript price, so a refused parent's
+// following calls cost one small file read each.
+async function refusal_for(
+	transcript: string,
+	now_ms: number,
+	state: ParentCutState,
+): Promise<string | undefined> {
+	const stamp = hook_decision.create_refusal_stamp(STAMP_PREFIX)
+	const target = stamp.path(transcript)
+
+	if (is_quiet(target, now_ms) || !(await is_due(state))) return undefined
+
+	return stamp.record(target, now_ms) ? PARENT_CUT_REASON : undefined
+}
+
+// A delegated unit's call names the *parent's* transcript and runs under the parent's process, so the
+// carry record reads as owned here; only `agent_id` tells it apart (`hook-decision.ts`). Refusing it
+// would hand the unit a hand-off it cannot take and spend the parent's quiet window on it.
+function is_unit_call(raw_payload: string): boolean {
+	try {
+		return (hook_decision.parse_hook_payload(raw_payload)?.agent_id ?? '') !== ''
+	} catch {
+		return false
+	}
+}
+
+function is_exempt(raw_payload: string): boolean {
+	return !hook_decision.is_switch_enabled(SWITCH_ENV_KEY) || is_unit_call(raw_payload)
+}
+
+/**
+ * The deny reason for a call a `backlogrun` parent makes past the shared threshold, or `undefined` when
+ * the call proceeds — a lane child, a delegated unit, a person's session, a handed-off or capped
+ * record, an `under` or unmeasurable verdict, or a call inside the quiet window after a refusal.
+ */
+async function parent_cut_reason(
+	raw_payload: string,
+	now_ms: number = Date.now(),
+	state: ParentCutState = current_state(),
+): Promise<string | undefined> {
+	if (is_exempt(raw_payload)) return undefined
+
+	const transcript = run_watcher_hook.transcript_of(raw_payload)
+
+	if (transcript === undefined) return undefined
+
+	return await refusal_for(transcript, now_ms, state)
+}
+
+const run_parent_cut_hook = {
+	PARENT_CUT_REASON,
+	QUIET_WINDOW_MS,
+	SWITCH_ENV_KEY,
+	parent_cut_reason,
+}
+
+export type { ParentCutState }
+export { run_parent_cut_hook }

package/scripts/run/run-preflight.ts

@@ -1,5 +1,5 @@
+import { git_gh_pr_read } from '#scripts/gh/git-gh-pr-read'
 import { git_command } from '#scripts/git/git-command'
-import { git_gh_pr_read } from '#scripts/git/git-gh-pr-read'
 import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
 import { z } from 'zod'
 import { run_hold } from './run-hold'
@@ -89,7 +89,7 @@ const STASH_LABEL_PREFIX = 'run:hold reclaimed before #'
 // so the shape it may take is pinned beside the interpolation rather than only in the CLI that
 // happens to be today's single caller. `run:liveness` interpolates it the same way, so the pattern
 // and the refusal live in one module both read (joshuafolkken/kit#1485).
-const { ISSUE_NUMBER_PATTERN, require_issue_number } = run_issue_number
+const { require_issue_number } = run_issue_number
 const UNREADABLE_PR_MESSAGE = 'The pull request could not be read for branch '
 
 function needs_reclaim(tree: TreeState): boolean {
@@ -385,15 +385,8 @@ async function check(issue: string): Promise<PreflightDecision> {
 }
 
 const run_preflight = {
-	CLEAN_ADVICE,
-	CLEAN_REASON,
 	CLEAN_VERDICT,
-	ISSUE_NUMBER_PATTERN,
-	PARK_ADVICE,
-	PARK_VERDICT,
-	RECLAIM_VERDICT,
 	RESUME_ADVICE,
-	RESUME_VERDICT,
 	MERGED_PR,
 	STASH_LABEL_PREFIX,
 	check,

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

@@ -1,6 +1,6 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
-import { git_stash } from '#scripts/git/git-stash'
+import { git_stash } from '#scripts/git/stash/git-stash'
 import { issue_read_cli, type BlockRead } from '#scripts/issue/issue-read-cli'
 import { issue_state_cli, type StateRead } from '#scripts/issue/issue-state-cli'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
@@ -150,7 +150,7 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 // `gather` and `to_parts` are exported so `run:next` reads the same state from the same three reads
 // rather than growing a second copy of the gather (joshuafolkken/kit#2188) — `run:next` is the
 // consumer of `run:prep` the epic #2166 wanted.
-const run_prep_cli = { USAGE, gather, main, parse_number, run, to_parts }
+const run_prep_cli = { gather, parse_number, run, to_parts }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
 

package/scripts/run/run-prep-locate.ts

@@ -159,7 +159,7 @@ async function locate(text: string): Promise<string> {
 	return format_locations(located)
 }
 
-const run_prep_locate = { extract_targets, format_locations, locate, parse_hits }
+const run_prep_locate = { extract_targets, locate, parse_hits }
 
 export type { Hit, Located }
 export { run_prep_locate }

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

@@ -28,7 +28,7 @@ import { run_progress_read, type ObservationRead } from './run-progress-read'
 // `backlogrun` parent — `ready #N · free lanes N` — which is itself something the parent acts on.
 //
 // **It cannot send a Telegram.** That is structural rather than a promise — nothing here imports
-// `scripts/git/telegram-notify`, which is the only egress there is. A heartbeat every twenty minutes on
+// `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.
 
@@ -347,10 +347,13 @@ async function run_ticks(
 	let loop = seed_loop(target, started_ms)
 
 	while (Date.now() - started_ms < options.max_ms && !run_progress_clock.is_life_ended(life)) {
+		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
 		await sleep(options.tick_ms)
 		run_progress_clock.ping_life(life)
+		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
 		loop = await step(options, target, loop)
 
+		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
 		const exit = await wait_exit(loop, wait)
 
 		if (exit !== undefined) return exit
@@ -491,27 +494,21 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 }
 
 const run_progress_cli = {
-	DECLINE_RETRY_SECONDS,
 	DEFAULT_MAX_HOURS,
 	DISABLED_NOTICE,
 	FAILED_TICK_PREFIX,
 	FRESH_LOOP,
 	IDLE_NOTICE,
 	LANE_CHILD_NOTICE,
-	MARKED_NOTICE,
 	REPO_UNRESOLVED_NOTICE,
-	TICK_SECONDS,
 	UNREADABLE_NOTICE,
 	USAGE,
 	WAIT_EXPIRED_NOTICE,
-	main,
 	read_arguments: run_progress_args.read_arguments,
-	report_decline,
 	run,
 	step,
 	to_interval_ms: run_progress_args.to_interval_ms,
 	to_max_ms: run_progress_args.to_max_ms,
-	to_options,
 	wait_once,
 }
 

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

@@ -1,6 +1,5 @@
-import { git_utilities } from '#scripts/git/constants'
+import { git_common_directory } from '#scripts/git/git-common-directory'
 import { stamp_file } from '#scripts/josh/stamp-file'
-import { execaSync } from 'execa'
 import { z } from 'zod'
 
 // The report clock `josh run:progress` keeps, in the one form both of its readers can use
@@ -16,9 +15,10 @@ import { z } from 'zod'
 //
 // **The key is the work tree's own git directory**, the way `run_hold` keys its record: two lanes of
 // one repository are two runs, and one lane's report must not silence the other's clock. The
-// synchronous twin asks `git rev-parse --absolute-git-dir`, which is the first of the two lines
-// `git_command.git_directories` reads and the one the asynchronous path already takes — so the two
-// spellings cannot name different files.
+// synchronous twin is `git_common_directory.own()`, which asks the same two lines
+// `git_command.git_directories` reads and takes the first — so the two spellings cannot name different
+// files. A git read that fails or times out answers `undefined`, which reads as "no clock here" and
+// lets the call through.
 
 const PROGRESS_PREFIX = 'josh-run-progress-'
 // The watcher's own liveness record, kept apart from the report clock above: that one says *when* the
@@ -55,14 +55,6 @@ const MS_PER_MINUTE = 60_000
 const LOG_STALE_MINUTES = 90
 const LOG_STALE_MS = LOG_STALE_MINUTES * MS_PER_MINUTE
 const BLOCK_SEPARATOR = '\n\n'
-// The lookup only ever decides whether a rule speaks, so a git call that hangs must not hold the hook
-// that is holding the user's call. A timeout answers `undefined`, which reads as "no clock here" and
-// lets the call through — the direction every other failure in this path already takes.
-const GIT_TIMEOUT_MS = 5000
-// The first of the two lines `git_command.git_directories` reads, asked on its own because that is the
-// one the record is keyed on. Asking git rather than assuming a directory named `.git` is what makes a
-// linked work tree, a bare repository and a `--separate-git-dir` clone all answer correctly.
-const GIT_DIRECTORY_ARGUMENTS: ReadonlyArray<string> = ['rev-parse', '--absolute-git-dir']
 
 // `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
@@ -259,25 +251,8 @@ function end_life(target: string): void {
 	stamp_file.remove_stamp(target)
 }
 
-// execa runs the binary directly with an argument array and no `shell` option, so CLI args cannot
-// break out of a shell sandbox; the git command and args are internally controlled, never untrusted
-// input. tssecurity:S8705 is a false positive here.
-function git_directory_sync(): string | undefined {
-	const git_binary = git_utilities.get_git_command_for_spawn()
-	const result = execaSync(git_binary, GIT_DIRECTORY_ARGUMENTS, {
-		reject: false,
-		timeout: GIT_TIMEOUT_MS,
-	}) // NOSONAR
-
-	if (result.exitCode !== 0) return undefined
-
-	const output = result.stdout.trim()
-
-	return output === '' ? undefined : output
-}
-
 function stamp_target_sync(): string | undefined {
-	const directory = git_directory_sync()
+	const directory = git_common_directory.own()
 
 	return directory === undefined ? undefined : stamp_target_of(directory)
 }
@@ -299,8 +274,6 @@ const run_progress_clock = {
 	LIFE_PREFIX,
 	LOG_KEEP,
 	LOG_STALE_MS,
-	PROGRESS_PREFIX,
-	append_line,
 	begin_life,
 	end_life,
 	is_life_ended,
@@ -314,7 +287,6 @@ const run_progress_clock = {
 	read_last_report,
 	read_last_report_sync,
 	stamp_target_of,
-	stamp_target_sync,
 }
 
 export { run_progress_clock }

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

@@ -27,8 +27,6 @@ import { run_progress } from './run-progress'
 // watcher it guards kept the default, which is the one state this module exists to prevent.
 
 const PACKAGE_FILE = 'package.json'
-const CONFIG_FIELD = 'josh'
-const INTERVAL_FIELD = 'progress_interval_minutes'
 
 // Deep enough to cross a workspace package and its root, and bounded so a path that never reaches a
 // root — a broken mount, a mocked `dirname` — cannot spin.
@@ -108,8 +106,6 @@ function configured_interval_ms(directory: string = process.cwd()): number {
 }
 
 const run_progress_config = {
-	CONFIG_FIELD,
-	INTERVAL_FIELD,
 	PACKAGE_FILE,
 	configured_interval_ms,
 	read_package_minutes,

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

@@ -28,7 +28,7 @@ import { run_progress_clock } from './run-progress-clock'
 // `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.
-const { PROGRESS_PREFIX, mark, parse_stamp, read_last_report } = run_progress_clock
+const { mark, parse_stamp, read_last_report } = run_progress_clock
 
 const FIRST_LOAD_AVERAGE = 0
 
@@ -78,7 +78,7 @@ async function to_child(issue: OpenIssueData): Promise<ChildObservation> {
 	const number = String(issue.number)
 	const child = await run_preflight.read_child_state(number)
 
-	return { issue: number, labels: to_labels(issue), pr_state: child.pr_state }
+	return { issue: number, title: issue.title, labels: to_labels(issue), pr_state: child.pr_state }
 }
 
 async function read_children(repo: string): Promise<ReadonlyArray<ChildObservation> | undefined> {
@@ -171,6 +171,7 @@ async function read_observations(request: ObservationRequest): Promise<Observati
 	if (children.length === 0 && !(await has_run_started(lanes))) return IDLE_READ
 
 	const observations: Observations = {
+		repo: request.repo,
 		children,
 		lanes,
 		load_average: loadavg()[FIRST_LOAD_AVERAGE] ?? 0,
@@ -181,7 +182,6 @@ async function read_observations(request: ObservationRequest): Promise<Observati
 }
 
 const run_progress_read = {
-	PROGRESS_PREFIX,
 	has_run_started,
 	live_target,
 	log_target,

package/scripts/run/run-progress.ts

@@ -1,3 +1,5 @@
+import { issue_cite, type IssueCiter } from '#scripts/issue/issue-cite'
+
 // `josh run:progress` — the one line an unattended run prints when it has gone quiet, and the clock
 // that decides when that is (joshuafolkken/kit#1520).
 //
@@ -56,6 +58,9 @@ const DEFAULT_INTERVAL_MS = DEFAULT_INTERVAL_MINUTES * MS_PER_MINUTE
 // a second spelling of it — `none` / `open` / `merged` / `closed`.
 interface ChildObservation {
 	issue: string
+	// Kept from the `in-progress` listing the child was read from, so the line cites it in full
+	// (joshuafolkken/kit#2943) without a read per child.
+	title: string
 	labels: ReadonlyArray<string>
 	pr_state: string
 }
@@ -66,6 +71,8 @@ interface LaneObservation {
 }
 
 interface Observations {
+	// `owner/repo`, the repository the listing was read from — what every printed issue links into.
+	repo: string
 	children: ReadonlyArray<ChildObservation>
 	lanes: ReadonlyArray<LaneObservation>
 	load_average: number
@@ -195,26 +202,32 @@ function next_state(
 	return { key, unchanged_since_ms: now_ms }
 }
 
-function format_child(child: ChildObservation): string {
+// The issue leads as a citation rather than a bare `#N` (joshuafolkken/kit#2943): the parent relays these
+// lines verbatim, and a bare number copied into a reply is what the Stop guard sends back.
+function format_child(child: ChildObservation, cite: IssueCiter): string {
 	const labels = child.labels.length > 0 ? child.labels.join(',') : '(no labels)'
 
-	return `#${child.issue} ${labels} PR:${child.pr_state}`
+	return `${cite(child.issue)} ${labels} PR:${child.pr_state}`
 }
 
 // An empty set is the pre-label stage, said as such rather than left as a blank slot between the
 // separators (joshuafolkken/kit#1900). After that change a `read_observations` result carries no
 // children exactly when a run has started and none has reached `in-progress` yet, so this is the one
 // place the two cases are told apart on the line.
-function format_children(children: ReadonlyArray<ChildObservation>): string {
+function format_children(children: ReadonlyArray<ChildObservation>, repo: string): string {
 	if (children.length === 0) return NO_CHILD_YET
+	const cite = issue_cite.citer(repo, new Map(children.map((child) => [child.issue, child.title])))
 
-	return children.map((child) => format_child(child)).join(' · ')
+	return children.map((child) => format_child(child, cite)).join(' · ')
 }
 
-function format_lanes(lanes: ReadonlyArray<LaneObservation>): string {
+// A lane is linked without its title: a lane in flight is a child the line above already cited in full,
+// so repeating the title here would only lengthen the line.
+function format_lanes(lanes: ReadonlyArray<LaneObservation>, repo: string): string {
 	if (lanes.length === 0) return NO_LANES
+	const cite = issue_cite.citer(repo, new Map())
 
-	return lanes.map((lane) => `${lane.issue}:${lane.state}`).join(' ')
+	return lanes.map((lane) => `${cite(lane.issue)}:${lane.state}`).join(' ')
 }
 
 // Absent is said, never filled in. A run started without a transcript path prints `unread` here, which
@@ -244,7 +257,7 @@ interface LineTiming {
  * this is that same move for one value.
  *
  * **It is a schedule rather than an observation, and the two conditions on it are said in prose**
- * (`docs/josh-commands.md` → `josh run:progress`): it holds only while the silence continues, and a
+ * (`docs/josh-commands-automation.md` → `josh run:progress`): it holds only while the silence continues, and a
  * real report arriving first restarts the clock through `--mark` and supersedes it. The line printing
  * it is itself a report, so the clock starts at this observation.
  */
@@ -303,8 +316,8 @@ function format_line(observations: Observations, timing: LineTiming): string {
 		observed_at: format_observed_at(timing.now_ms),
 		quiet: format_minutes(timing.now_ms - timing.quiet_since_ms),
 		unchanged: format_minutes(timing.now_ms - timing.unchanged_since_ms),
-		children: format_children(observations.children),
-		lanes: format_lanes(observations.lanes),
+		children: format_children(observations.children, observations.repo),
+		lanes: format_lanes(observations.lanes, observations.repo),
 		load: observations.load_average.toFixed(1),
 		record: format_record(observations.record_age_ms),
 		next: format_next_report(timing.now_ms, timing.interval_ms),
@@ -354,7 +367,6 @@ const run_progress = {
 	format_line,
 	format_next_line,
 	format_next_report,
-	format_record,
 	format_report,
 	is_due,
 	minutes_from,