@joshuafolkken/kit 1.1240.0 → 1.1370.0

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

@@ -1,8 +1,11 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { session_cite } from '#scripts/issue/session-cite'
 import { josh_command } from '#scripts/josh/josh-run'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
 import { run_cut_report } from '#scripts/run/cut/run-cut-report'
+import { run_event_plan } from '#scripts/run/event/run-event-plan'
 import { run_hold_cli } from '#scripts/run/hold/run-hold-cli'
 import { run_halfrun_resume } from '#scripts/run/run-halfrun-resume'
 import { run_label } from '#scripts/run/run-label'
@@ -10,17 +13,21 @@ import { run_next } from '#scripts/run/run-next'
 import { run_prep } from '#scripts/run/run-prep'
 import { run_prep_cli } from '#scripts/run/run-prep-cli'
 import { run_prrun_resume } from '#scripts/run/run-prrun-resume'
-import { run_stage, type StageCommand, type StageDecision } from '#scripts/run/run-stage'
+import {
+	run_stage,
+	type StageCommand,
+	type StageDecision,
+	type StageState,
+} from '#scripts/run/run-stage'
 import { run_stage_read, type StageRead } from '#scripts/run/run-stage-read'
 import { run_step } from '#scripts/run/run-step'
 import { run_entry, type EntryParts } from './run-entry'
 import { run_entry_stop } from './run-entry-stop'
 
-// `josh run:entry <N>` — one call for the fixed entry sequence a lane opens on (joshuafolkken/kit#2372).
-// The loop used to spend a round trip on `run:hold`, one on `cost --cut`, one on `run:prep` and one on
-// `run:step`, re-billing a lane's full context each time; this runs all four internally and prints one
-// composite report, the same way `backlog:offer` folds `backlog:next` → `backlog:budget` and `run:prep`
-// folds three reads.
+// `josh run:entry <N>` — one call for the fixed entry sequence a lane opens on. Rather than a round
+// trip each on `run:hold`, `cost --cut`, `run:prep` and `run:step`, re-billing a lane's full context
+// each time, this runs all four internally and prints one composite report, the same way
+// `backlog:offer` folds `backlog:next` → `backlog:budget` and `run:prep` folds three reads.
 //
 // **The stops short-circuit.** A `busy` / `unknown` hold and an `over` budget both end the run, so the
 // composite reports them without reading the issue — the gate `fullrun.md` steps 1 and 3 stop on stays a
@@ -31,7 +38,6 @@ import { run_entry_stop } from './run-entry-stop'
 const ARGV_OFFSET = 2
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
-const ISSUE_NUMBER_PATTERN = /^[1-9]\d*$/u
 const USAGE = 'Usage: josh run:entry <issue-number> [--to kickoff|halfrun|prrun|fullrun]'
 const TO_FLAG = '--to'
 // The flag and its command.
@@ -50,7 +56,11 @@ const HALFRUN_RESUME_TOKEN = 'halfrun'
 function parse_number(argv: ReadonlyArray<string>): string | undefined {
 	const [first] = argv
 
-	if (first === undefined || argv.length !== 1 || !ISSUE_NUMBER_PATTERN.test(first)) {
+	if (
+		first === undefined ||
+		argv.length !== 1 ||
+		!issue_number_shape.ISSUE_NUMBER_PATTERN.test(first)
+	) {
 		return undefined
 	}
 
@@ -62,7 +72,7 @@ interface EntryRequest {
 	command: StageCommand
 }
 
-// `--to <command>` names how far the run goes (joshuafolkken/kit#3042); absent, it is `fullrun`.
+// `--to <command>` names how far the run goes; absent, it is `fullrun`.
 // Anything else is refused.
 function parse_command(rest: ReadonlyArray<string>): StageCommand | undefined {
 	if (rest.length === 0) return run_stage.DEFAULT_COMMAND
@@ -87,7 +97,7 @@ function first_line(out: string): string {
 
 // `run:hold <N>` prints one token — `hold`, `busy` or `unknown` — and forwards its explanation to
 // stderr, so the composite branches on the token and the reader still sees why. `--fullrun` marks the
-// hold as a run whose implementation cut resumes as `fullrun #N` (joshuafolkken/kit#2760) — a
+// hold as a run whose implementation cut resumes as `fullrun #N` — a
 // `fullrun`'s, and a `prrun`'s, which runs `fullrun`'s steps; a `halfrun`'s hold is never marked.
 async function claim_hold(issue_number: string, command: StageCommand): Promise<string> {
 	const mark = command === run_stage.HALFRUN ? [] : ['--fullrun']
@@ -116,7 +126,7 @@ interface Reads {
 }
 
 // The issue reads and the pre-implementation verdict, from the one gather `run:prep` and `run:next`
-// already share (joshuafolkken/kit#2188) rather than a second copy — the report is `run:prep`'s
+// already share rather than a second copy — the report is `run:prep`'s
 // formatter, the verdict is `run:step`'s `pre_verdict` over the same parts.
 async function gather_reads(issue_number: string): Promise<Reads> {
 	const reads = await run_prep_cli.gather(issue_number)
@@ -127,7 +137,7 @@ async function gather_reads(issue_number: string): Promise<Reads> {
 }
 
 function emit(parts: EntryParts): number {
-	console.info(run_entry.format_report(parts))
+	console.info(session_cite.text(run_entry.format_report(parts)))
 
 	return run_entry.exit_code(parts)
 }
@@ -138,7 +148,7 @@ function stop_report(issue_number: string, hold: string, cost: string, report: s
 	return emit({ issue_number, hold, cost, verdict: run_entry.NO_VERDICT, report })
 }
 
-// A stop this command decided carries its own chores (joshuafolkken/kit#3099): the `confirmation`
+// A stop this command decided carries its own chores: the `confirmation`
 // Telegram always, and the release where this call claimed the hold — `run_entry_stop` says why.
 interface StopCall {
 	parts: Pick<EntryParts, 'issue_number' | 'hold' | 'cost' | 'report'>
@@ -160,9 +170,9 @@ interface Resume {
 	code: number
 }
 
-// **A resume is asked before the hold is claimed** (joshuafolkken/kit#2760). An implementation cut
-// outside a lane keeps its hold, so the fresh session's `fullrun #N` would be refused `busy` by its own
-// run's hold before it ever reached `run:cut --resume` — the hand-off the cut promised could not land.
+// **A resume is asked before the hold is claimed.** An implementation cut outside a lane keeps its
+// hold, so the fresh session's `fullrun #N` would otherwise be refused `busy` by its own run's hold
+// before it ever reached `run:cut --resume` — the hand-off the cut promised could not land.
 async function ask_resume(issue_number: string): Promise<Resume> {
 	const asked = await josh_command.josh_run(
 		['run:cut', '--resume', issue_number],
@@ -175,16 +185,16 @@ async function ask_resume(issue_number: string): Promise<Resume> {
 // Anything but `fresh` is `run:cut --resume`'s answer to act on (`pre-gate-cut.md`), not a new run: the
 // token and its exit code are passed through, and nothing is claimed or read.
 function resume_report(issue_number: string, resume: Resume): number {
-	console.info(`entry #${issue_number} — resume: ${resume.token}`)
+	console.info(`entry ${session_cite.issue(issue_number)} — resume: ${resume.token}`)
 
 	return resume.code
 }
 
-// **A `halfrun` stopped before its commit is resumed, not claimed** (joshuafolkken/kit#2796): its hold
+// **A `halfrun` stopped before its commit is resumed, not claimed**: its hold
 // is kept over the verified diff, so the claim below would answer `busy` against it. The budget is asked
 // first, as for any run; then the hold is adopted and the run goes to the gate, skipping everything up
-// to and including implementation. **A `prrun` stopped before its merge is resumed the same way**
-// (joshuafolkken/kit#3023), under the token that says what is left of it.
+// to and including implementation. **A `prrun` stopped before its merge is resumed the same way**,
+// under the token that says what is left of it.
 async function resume_stopped(
 	{ issue_number, command }: EntryRequest,
 	token: string,
@@ -204,7 +214,7 @@ async function resume_stopped(
 		return await stop_run({ parts, command, reason: HOLD_REASON, should_release: false })
 	}
 
-	console.info(`entry #${issue_number} — resume: ${token}`)
+	console.info(`entry ${session_cite.issue(issue_number)} — resume: ${token}`)
 
 	return SUCCESS_EXIT_CODE
 }
@@ -225,15 +235,21 @@ async function resume_any(
 		: await resume_stopped(request, stage.prrun_token, run_prrun_resume)
 }
 
-// **A command whose stopping point the issue has already reached redoes nothing** (joshuafolkken/kit#3042)
-// — the stage line is the whole report. A merged issue is the exception: the ordinary entry already
+// **A command whose stopping point the issue has already reached redoes nothing** — the stage line is
+// the whole report. A merged issue is the exception: the ordinary entry already
 // answers it (`already-done`, or `keep-work` over a lane's uncommitted work), so it is left to that.
 function is_settled(decision: StageDecision): boolean {
 	return decision.is_reached && decision.state !== run_stage.MERGED
 }
 
+// A planned issue was planned by `kickoff`, whose entry claims nothing, so the claim that starts past
+// the plan writes the `plan` event `run:board` draws 📝 from.
+async function mark_planned(issue_number: string, state: StageState): Promise<void> {
+	if (state === run_stage.PLANNED) await run_event_plan.emit_plan(issue_number)
+}
+
 // The tree is held and the budget allows the run, so the issue is marked as running before its reads
-// (joshuafolkken/kit#3182) — the label then shows in the `labels:` line the report below carries.
+// — the label then shows in the `labels:` line the report below carries.
 async function proceed(issue_number: string, hold: string, cost: string): Promise<number> {
 	await run_label.mark(issue_number)
 	const reads = await gather_reads(issue_number)
@@ -241,7 +257,10 @@ async function proceed(issue_number: string, hold: string, cost: string): Promis
 	return emit({ issue_number, hold, cost, verdict: reads.verdict, report: reads.report })
 }
 
-async function claim_run({ issue_number, command }: EntryRequest): Promise<number> {
+async function claim_run(
+	{ issue_number, command }: EntryRequest,
+	state: StageState,
+): Promise<number> {
 	const hold = await claim_hold(issue_number, command)
 
 	if (hold !== run_hold_cli.HOLD_VERDICT) {
@@ -258,6 +277,8 @@ async function claim_run({ issue_number, command }: EntryRequest): Promise<numbe
 		return await stop_run({ parts, command, reason: BUDGET_REASON, should_release: true })
 	}
 
+	await mark_planned(issue_number, state)
+
 	return await proceed(issue_number, hold, cost)
 }
 
@@ -283,11 +304,11 @@ async function open_run(request: EntryRequest): Promise<number> {
 	const stage = await run_stage_read.read_stage(issue_number)
 	const decision = run_stage.decide(stage.state, command)
 
-	console.info(run_stage.format_decision(issue_number, decision))
+	console.info(session_cite.text(run_stage.format_decision(issue_number, decision)))
 
 	if (command === run_stage.KICKOFF || is_settled(decision)) return SUCCESS_EXIT_CODE
 
-	return (await resume_any(request, decision, stage)) ?? (await claim_run(request))
+	return (await resume_any(request, decision, stage)) ?? (await claim_run(request, decision.state))
 }
 
 async function run(argv: ReadonlyArray<string>): Promise<number> {

package/scripts/run/entry/run-entry-stop.ts

@@ -1,15 +1,13 @@
+import { issue_cite } from '#scripts/issue/issue-cite'
 import { josh_command } from '#scripts/josh/josh-run'
 import { telegram_notify } from '#scripts/notify/telegram-notify'
 import { lane_park } from '#scripts/rules/lane-park'
 
-// What `run:entry` does on the way out of a stop it decided itself (joshuafolkken/kit#3099).
+// What `run:entry` does on the way out of a stop it decided itself.
 //
-// **The stop's chores used to be the agent's to remember, and the `Stop` hook was what reminded it.**
-// `fullrun.md` step 3 asked the agent, on an `over` budget, to send the `confirmation` Telegram and then
-// run `pnpm josh run:release` — two calls after a command had already decided the run was over. Across
-// eleven measured sessions the hook sent a reply back five times for exactly those two calls, each one a
-// further turn re-reading the whole context. The command that decides the stop knows everything the
-// chores need, so it does them, and the hook stays a safety net that a normal run never trips.
+// **The command that decides the stop does its chores** — the `confirmation` Telegram and the hold
+// release — because it knows everything they need, and leaving them to the agent costs further turns
+// re-reading the whole context. The `Stop` hook stays a safety net that a normal run never trips.
 //
 // **The release is the claim's own undo, and only where this call made the claim.** A resume over a
 // stopped `halfrun` / `prrun` stops on the budget before adopting anything, and the hold there is the
@@ -58,7 +56,7 @@ function is_parking_child(): boolean {
 const DEFAULT_PORTS: StopPorts = { notify: telegram_notify.confirm, release, is_parking_child }
 
 function body_of(notice: StopNotice): string {
-	return `${notice.command} #${notice.issue_number} stopped at entry: ${notice.reason}.\nResume with \`${notice.command} #${notice.issue_number}\`.`
+	return `${notice.command} ${issue_cite.plain(notice.issue_number)} stopped at entry: ${notice.reason}.\nResume with \`${notice.command} ${issue_cite.plain(notice.issue_number)}\`.`
 }
 
 // The release runs first, so the resume the Telegram names finds the tree free when a person acts on it.
@@ -77,7 +75,7 @@ async function notify_stop(notice: StopNotice, ports: StopPorts): Promise<void>
 	if (ports.is_parking_child()) return
 
 	const is_sent = await ports.notify({
-		issue_title: `${notice.command} #${notice.issue_number} stopped`,
+		issue_title: `${notice.command} ${issue_cite.plain(notice.issue_number)} stopped`,
 		body: body_of(notice),
 		recovery: RECOVERY,
 	})

package/scripts/run/entry/run-entry.ts

@@ -1,12 +1,11 @@
 import { run_hold_cli } from '#scripts/run/hold/run-hold-cli'
 import { run_step } from '#scripts/run/run-step'
 
-// `josh run:entry <N>` — the one call a `fullrun` makes to open a run (joshuafolkken/kit#2372). It
-// folds the fixed entry sequence a lane spends four separate round trips on — claim the tree
-// (`run:hold`), read the session budget (`cost --cut`), gather the issue reads (`run:prep`), and decide
-// the pre-implementation step (`run:step`) — into one composite, the same shape `backlog:offer` folded
-// the parent loop head on (joshuafolkken/kit#2162). Context cost grows with the square of a lane's
-// round trips, so collapsing four into one is where the fold pays the most.
+// `josh run:entry <N>` — the one call a `fullrun` makes to open a run. It folds the fixed entry
+// sequence of four round trips — claim the tree (`run:hold`), read the session budget (`cost --cut`),
+// gather the issue reads (`run:prep`), and decide the pre-implementation step (`run:step`) — into one
+// composite, the same shape `backlog:offer` gives the parent loop head. Context cost grows with the
+// square of a lane's round trips, so collapsing four into one is where the fold pays the most.
 //
 // **This module is the pure half**, kept apart from the chaining CLI the way `run-prep.ts` is kept from
 // `run-prep-cli.ts` and `run-review.ts` from its steps. It shapes the summary line the reader branches

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

@@ -10,20 +10,19 @@ import { run_event_stream_emit } from './run-event-stream-emit'
 import { run_event_watch } from './run-event-watch'
 
 // `josh run:event` — the command a run's step calls to append to, or read back, the append-only event
-// stream (joshuafolkken/kit#2205). The in-process seams (`run:merge`) append directly; the steps with no
+// stream. The in-process seams (`run:merge`) append directly; the steps with no
 // josh command at the point the event happens — a plan posted, a child launched, a PR opened, a stop —
 // call `--append` here, so parent and lane child alike write to the one stream. `--from` is the woken
 // reader's "everything since the position I last read"; `--last` is the degenerate single-event read.
 //
-// **`--follow` is one bounded read that waits** (joshuafolkken/kit#2207). It is `--from` that returns
+// **`--follow` is one bounded read that waits.** It is `--from` that returns
 // the moment an event is past the given position, and otherwise at the interval. The lines go to
 // standard output and the position to read from next goes to standard error — the same before and after
 // a session cut, because the stream is the run's and the position is the caller's.
 //
-// **`--watch` is the ambient surface: the same pass in a loop that never exits** (joshuafolkken/kit#2492),
-// each event rendered in the session language (`run-event-render.ts`), for a person to keep open in a
-// pane of their own. No conversation relays the stream any more — a session woken per event re-read its
-// whole history each time, and outspent every lane of the run doing it.
+// **`--watch` is the ambient surface: the same pass in a loop that never exits**, each event rendered
+// in the session language (`run-event-render.ts`), for a person to keep open in a pane of their own. No
+// conversation relays the stream — a session woken per event would re-read its whole history each time.
 
 const ARGV_OFFSET = 2
 const SUCCESS_EXIT_CODE = 0

package/scripts/run/event/run-event-filed.ts

@@ -0,0 +1,69 @@
+import { issue_cite } from '#scripts/issue/issue-cite'
+import {
+	BREAKING_CHANGE_LABEL,
+	BUG_LABEL,
+	ENHANCEMENT_LABEL,
+	has_label_name,
+} from '#scripts/issue/issue-labels'
+
+// The text of a `filed` event: the Issue a run filed, its kind, its title, and the child whose work
+// turned it up. `issue:file` writes it and `run:board` reads it back, both through this module, so the
+// two never spell it differently.
+
+// The classification labels a filing's kind is read from, in precedence order: a breaking change is
+// named as one whatever else it is.
+const KINDS = [BREAKING_CHANGE_LABEL, BUG_LABEL, ENHANCEMENT_LABEL] as const
+
+type FiledKind = (typeof KINDS)[number]
+
+interface Filed {
+	// `#<N>` for this repository's Issue, `<owner>/<repo>#<N>` for one filed elsewhere.
+	reference: string
+	// The filing's classification label; none where it carries none of `KINDS`, and on an event written
+	// before the kind was recorded.
+	kind: FiledKind | undefined
+	title: string
+	// The lane child that was working when the Issue was filed, when the filing came from one.
+	found_during: string | undefined
+}
+
+// The kind slot is always written, `[<label>]` or `[]`, against the reference with no space: an event
+// written before the kind always has the space there, so no title, whatever it opens with, reads as a
+// kind.
+const TEXT_PATTERN = new RegExp(
+	String.raw`^(?<reference>\S*#\d+)(?:\[(?<kind>${KINDS.join('|')}|)\])? (?<title>.*?)(?: \(found during #(?<during>\d+)\))?$`,
+	'u',
+)
+
+// Through the case-insensitive comparison GitHub applies, so a `--label Bug` filing is still a bug.
+function kind_of(labels: ReadonlyArray<string>): FiledKind | undefined {
+	return KINDS.find((kind) => has_label_name(labels, kind))
+}
+
+function text_of(filed: Filed): string {
+	const kind = `[${filed.kind ?? ''}]`
+	const suffix =
+		filed.found_during === undefined
+			? ''
+			: ` (found during ${issue_cite.plain(filed.found_during)})`
+
+	return `${filed.reference}${kind} ${filed.title}${suffix}`
+}
+
+function parse(text: string): Filed | undefined {
+	const groups = TEXT_PATTERN.exec(text)?.groups
+
+	if (groups === undefined) return undefined
+
+	return {
+		reference: String(groups['reference']),
+		kind: KINDS.find((kind) => kind === groups['kind']),
+		title: String(groups['title']),
+		found_during: groups['during'],
+	}
+}
+
+const run_event_filed = { kind_of, parse, text_of }
+
+export { run_event_filed }
+export type { Filed, FiledKind }

package/scripts/run/event/run-event-follow.ts

@@ -1,6 +1,6 @@
 import type { StreamRead } from './run-event-stream'
 
-// The follow read behind `josh run:event --follow` and `--watch` (joshuafolkken/kit#2207). A reader
+// The follow read behind `josh run:event --follow` and `--watch`. A reader
 // asks the run's event stream for "everything since the position I last read" — and must see **both** a
 // new event's arrival, promptly, and the interval passing when nothing new has happened, so a person
 // watching sees progress land at once and still sees the run is alive when it is quiet.
@@ -8,12 +8,12 @@ import type { StreamRead } from './run-event-stream'
 // **This is one bounded pass, not the loop.** It returns as soon as any event is past the caller's
 // position (the arrival), or when the interval elapses having found none (the quiet tick); the caller
 // shows what came back and asks again from the returned position. The loop is `run-event-watch.ts`,
-// run in a pane of its own rather than by a session restarting the pass (joshuafolkken/kit#2492).
+// run in a pane of its own rather than by a session restarting the pass.
 //
 // **It reads the run's stream, not a session's.** `read` is `run_event_stream.read_from` bound to the
 // run-keyed target, and the position is the caller's own, so the pass answers the same before and after
 // a `backlogrun` session cut: a cut changes who executes, never what the stream says or where a reader
-// stands in it. That invariant is the point of the whole issue, and it is why this takes ports rather
+// stands in it. That invariant is why this takes ports rather
 // than resolving a target itself — the test drives it with a stream it controls and a clock it advances.
 //
 // **It is a poll, and deliberately not `run:progress`'s loop.** That one reads GitHub observations and

package/scripts/run/event/run-event-plan.ts

@@ -0,0 +1,38 @@
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { run_event_scope } from './run-event-scope'
+import { run_event_stream, type RunEvent } from './run-event-stream'
+import { run_event_stream_emit } from './run-event-stream-emit'
+
+// The `plan` event `run:board` draws 📝 from, written by code rather than by a step a child runs by hand,
+// which children skip — and every `run:planned` issue's entry starts past the plan. Two callers write
+// it: `run:entry` when a planned issue is claimed, and the first implementation edit of a lane child,
+// which is where the Step 0 work summary falls due. **Once per launch of the issue**, so the second
+// of the two adds nothing, while a re-dispatched child — whose launch restarts its `run:board` track —
+// writes its own.
+
+const KIND = run_event_stream.EVENT_KIND.PLAN
+const PLAN_VERB = 'planned'
+
+function plan_text(issue: string): string {
+	return `${PLAN_VERB} ${issue_cite.plain(issue)}`
+}
+
+function has_plan(events: ReadonlyArray<RunEvent>, issue: string): boolean {
+	return run_event_scope
+		.since_own_launch(events, issue)
+		.some((event) => event.kind === KIND && run_event_scope.issue_named(event) === issue)
+}
+
+/**
+ * Append the issue's `plan` event unless its newest launch already carries one. Best-effort
+ * like every emit: a failed read is an empty invocation, a failed append is swallowed.
+ */
+async function emit_plan(issue: string): Promise<void> {
+	if (has_plan(await run_event_stream_emit.invocation_or_all_events(), issue)) return
+
+	await run_event_stream_emit.emit(KIND, plan_text(issue))
+}
+
+const run_event_plan = { emit_plan, plan_text }
+
+export { run_event_plan }

package/scripts/run/event/run-event-render.ts

@@ -1,9 +1,8 @@
 import type { EventKind, RunEvent } from './run-event-stream'
 
-// One run event as the line a person reads in the watch pane (joshuafolkken/kit#2492). The ambient tier
-// used to be a session relaying `run:event --follow`, and every relay re-read that session's whole
-// history; the pane is a script, so the wording a relaying session supplied is supplied here instead —
-// one label per event kind, in the session language, beside the local clock time.
+// One run event as the line a person reads in the watch pane. The pane is a script, not a session, so
+// the wording is supplied here — one label per event kind, in the session language, beside the local
+// clock time.
 //
 // **The kinds are a fixed enumeration** (`run-event-stream.ts` → `EVENT_KIND`), so a template table is
 // the whole renderer; a kind the table does not name — a stream written by a newer kit — prints its raw
@@ -40,6 +39,12 @@ const KIND_LABELS: Readonly<Record<EventKind, KindLabel>> = {
 	heartbeat: { ja: '生存確認', en: 'heartbeat' },
 	'ship-launch': { ja: '出荷を開始', en: 'ship launched' },
 	'ship-stop': { ja: '出荷が停止', en: 'ship stopped' },
+	idle: { ja: '新着待ち', en: 'idle watch' },
+	filed: { ja: '起票', en: 'filed' },
+	note: { ja: '意見', en: 'note' },
+	'lane-phase': { ja: 'レーンの段階', en: 'lane phase' },
+	add: { ja: '割り込み', en: 'added' },
+	'lane-limit': { ja: 'レーン上限', en: 'lane limit' },
 }
 
 const LABELS_BY_KIND: ReadonlyMap<string, KindLabel> = new Map(Object.entries(KIND_LABELS))

package/scripts/run/event/run-event-scope.ts

@@ -1,18 +1,16 @@
+import { issue_cite } from '#scripts/issue/issue-cite'
 import type { CarryRead } from '#scripts/run/carry/run-carry'
 import { run_event_stream, type RunEvent } from './run-event-stream'
 
-// The one place a stream consumer scopes the event stream to a single invocation (joshuafolkken/kit#2395).
-// The stream is the repository's event log, not this run's — it outlives every invocation by design — so a
-// consumer handed every event treats a previous invocation's merges, parks and cuts as its own. #2393 built
-// the fix (the carry record's `started_at` as the lower bound, filtered by each event's own time) but left
-// it private inside `run-report.ts`; every other consumer of the stream carried the same defect. This is that
-// mechanism, published once, so `run:report`, the retrospective digest and `run:step` share one time filter
-// rather than each writing it again — the second copy `CLAUDE.md` forbids as a clone.
+// The one place a stream consumer scopes the event stream to a single invocation. The stream is the
+// repository's event log, not this run's — it outlives every invocation by design — so a consumer handed
+// every event treats a previous invocation's merges, parks and cuts as its own. The carry record's
+// `started_at` is the lower bound, filtered by each event's own time, published once so `run:report`, the
+// retrospective digest and `run:step` share one time filter rather than each writing it again.
 //
 // **It never rounds an undetermined scope back to the whole stream.** A scope that cannot be determined — no
 // carry record, an unreadable one, or a start time that is not a time — answers `undefined`, and each
-// consumer falls to the "could not determine" side rather than showing every invocation's events, which is
-// exactly the rounding #2308 and #2393 named.
+// consumer falls to the "could not determine" side rather than showing every invocation's events.
 
 const SINCE_SCOPE = 'since'
 const UNKNOWN_SCOPE = 'unknown'
@@ -71,19 +69,19 @@ function scope_of(read: CarryRead): EventScope {
 
 // The newest event within scope, or `undefined` when the scope could not be determined or nothing falls
 // inside it. The "last line" consumers read this rather than the raw newest event, so a stale event a
-// previous invocation left on the stream is never read as this run's position (joshuafolkken/kit#2395).
+// previous invocation left on the stream is never read as this run's position.
 function last_scoped_event(
 	events: ReadonlyArray<RunEvent>,
 	scope: EventScope,
 ): RunEvent | undefined {
-	// Trace events (a `josh ship` stage line, joshuafolkken/kit#2426) are skipped, as `read_last` skips
+	// Trace events (a `josh ship` stage line) are skipped, as `read_last` skips
 	// them, so `run:step` reads the run's position rather than an unknown `ship-stage`.
 	return scoped_events(events, scope)?.findLast(
 		(event) => !run_event_stream.TRACE_KINDS.has(event.kind),
 	)
 }
 
-// The positions a detached `josh ship` supervisor leaves (joshuafolkken/kit#2428). Each names its issue
+// The positions a detached `josh ship` supervisor leaves. Each names its issue
 // (`#<N> …`), so they are self-scoping where the carry scope is not: the stream is shared by every lane,
 // and another lane's supervisor must never be read as this run's position.
 const SHIP_POSITION_KINDS: ReadonlySet<string> = new Set([
@@ -108,20 +106,27 @@ const BATCH_RECORD_KINDS: ReadonlySet<string> = new Set([
 const ISSUE_REFERENCE = /#(\d+)/u
 
 function is_foreign_ship_event(event: RunEvent, issue: string): boolean {
-	return SHIP_POSITION_KINDS.has(event.kind) && !event.text.startsWith(`#${issue} `)
+	return (
+		SHIP_POSITION_KINDS.has(event.kind) && !event.text.startsWith(`${issue_cite.plain(issue)} `)
+	)
 }
 
 function is_own_ship_event(event: RunEvent, issue: string): boolean {
 	return SHIP_POSITION_KINDS.has(event.kind) && !is_foreign_ship_event(event, issue)
 }
 
-// **A lane child's position is read only from events that name its own issue** (joshuafolkken/kit#3039).
-// The parent and every lane append to one stream under one carry scope, so anything else on it is another
-// run's: another lane's merge told a planned child to stop, the parent's stall (which names no issue)
-// pointed it at `backlog:next`, and another lane's cut at `run:cut --resume`. The child's own merge and
+// The issue an event's text names, the way every reader here — and `run:board` — keys an event to a child.
+function issue_named(event: RunEvent): string | undefined {
+	return ISSUE_REFERENCE.exec(event.text)?.[1]
+}
+
+// **A lane child's position is read only from events that name its own issue.** The parent and every
+// lane append to one stream under one carry scope, so anything else on it is another run's: another
+// lane's merge, the parent's stall (which names no issue) or another lane's cut would misdirect the
+// child. The child's own merge and
 // outage stay, so the parent-only stop in `run-step.ts` still holds; the parent keeps reading everything.
 function names_issue(event: RunEvent, issue: string): boolean {
-	return ISSUE_REFERENCE.exec(event.text)?.[1] === issue
+	return issue_named(event) === issue
 }
 
 function is_lane_position(event: RunEvent, issue: string): boolean {
@@ -164,12 +169,36 @@ function last_issue_event(
 	return own.findLast((event) => is_own_ship_event(event, issue))
 }
 
+// A child's launch and the endings `run:merge` settles it with — the ones `run:board` stops drawing it
+// running on. A park or a split already ran `run:merge`, so a child closed after one owes nothing.
+const LAUNCH_OR_SETTLE_KINDS: ReadonlySet<string> = new Set([
+	KIND.CHILD_LAUNCH,
+	KIND.MERGE,
+	KIND.PARK,
+	KIND.SPLIT,
+])
+
+// Whether this invocation's newest launch of the issue has not yet been settled.
+// `run:merge` is the merge event's one writer, so a child that closed without it stays running on
+// `run:board`; `run:step` reads this to point the parent at the merge. An undetermined scope owes nothing.
+function is_merge_owed(events: ReadonlyArray<RunEvent>, scope: EventScope, issue: string): boolean {
+	const newest = (scoped_events(events, scope) ?? []).findLast(
+		(event) => LAUNCH_OR_SETTLE_KINDS.has(event.kind) && names_issue(event, issue),
+	)
+
+	return newest?.kind === KIND.CHILD_LAUNCH
+}
+
 const run_event_scope = {
 	UNKNOWN_EVENT_SCOPE,
+	is_merge_owed,
+	issue_named,
 	last_issue_event,
 	last_scoped_event,
+	moment_of,
 	scope_of,
 	scoped_events,
+	since_own_launch,
 }
 
 export type { EventScope }