@joshuafolkken/kit 1.1784.0 → 1.2114.0

package/scripts/lane/lane-overrun.ts

@@ -0,0 +1,274 @@
+import { agent_argv } from '#scripts/agent/agent-argv'
+import { agent_role_profile } from '#scripts/agent/agent-role-profile'
+import { git_gh_issue_write } from '#scripts/gh/git-gh-issue-write'
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { process_identity } from '#scripts/josh/process-identity'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { detached_launch } from '#scripts/run/detached-launch'
+import { run_event_overrun, type OverrunNote } from '#scripts/run/event/run-event-overrun'
+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 { lane_breakdown, type Breakdown } from './lane-breakdown'
+import { lane_breakdown_implement } from './lane-breakdown-implement'
+import { lane_breakdown_text, type Report } from './lane-breakdown-text'
+import { lane_child_marker } from './lane-child-marker'
+import { lane_investigation_switch } from './lane-investigation-switch'
+import { lane_ledger, type LedgerEntry } from './lane-ledger'
+import { lane_net_time } from './lane-net-time'
+import { lane_overrun_prompt } from './lane-overrun-prompt'
+import { lane_tail_stats } from './lane-tail-stats'
+
+// A merged lane over the overrun threshold of net time is investigated for its causes
+// (joshuafolkken/kit#4751). `run:merge` asks at each merge: a lane at or under the threshold — its long
+// total spent waiting on a person or an outage included — stops here, before any record of it is read.
+// An overrun launches a detached worker session that reads the lane's records and files each unfiled
+// cause through `issue:file` — the causes one fix place shares as one issue, or folded into an open
+// issue touching the same files (joshuafolkken/kit#4858) — so the next lane starts without waiting on
+// it. The session carries the lane's child mark, which makes `issue:file` count its filings against the
+// lane (`issue-file-cap.ts`), and `--found-during` names the same origin; its overrun mark records the
+// filings as the investigation's, not the child's (joshuafolkken/kit#4880). The launch and the session's result both go on the run's
+// event stream as notes. It runs only while `JOSH_LANE_INVESTIGATION` is on (`lane-investigation-switch.ts`);
+// off by default, an overrun leaves a skipped note in place of the launch (joshuafolkken/kit#5044).
+
+const { EVENT_KIND } = run_event_stream
+const { DISABLED_REASON } = run_event_overrun
+const LOG_PREFIX = 'josh-lane-overrun-'
+const LOG_SUFFIX = '.log'
+const NO_LEDGER = 'no ledger'
+
+// A lane's net minutes and their breakdown by stage, or why there are none (joshuafolkken/kit#4818).
+// `is_commented` says an earlier pass of the lane commented the breakdown on its Issue already;
+// `entries` are the ledger rows the breakdown's details are read off (joshuafolkken/kit#5078).
+type LaneNet =
+	| {
+			kind: 'minutes'
+			minutes: number
+			breakdown: Breakdown
+			entries: ReadonlyArray<LedgerEntry>
+			is_commented: boolean
+	  }
+	| { kind: 'missing'; reason: string }
+
+// A launch that failed is retried once, at the next `run:merge` (joshuafolkken/kit#4930).
+const MAX_LAUNCH_FAILURES = 2
+
+function overrun_notes(events: ReadonlyArray<RunEvent>): ReadonlyArray<OverrunNote> {
+	return events.flatMap((event) =>
+		event.kind === EVENT_KIND.NOTE ? (run_event_overrun.parse(event.text) ?? []) : [],
+	)
+}
+
+// A pass that threw before it noted anything leaves a failure with no minutes.
+function is_thrown(note: OverrunNote): boolean {
+	return note.kind === 'failed' && note.minutes === undefined
+}
+
+// A start note that launched no session.
+function is_launch_failure(note: OverrunNote): boolean {
+	return note.kind === 'failed' && note.minutes !== undefined
+}
+
+function is_final(note: OverrunNote): boolean {
+	return !is_thrown(note) && !is_launch_failure(note)
+}
+
+// A merge `run:merge` collects again — a driver retry, a parent's hand run — finds its lane's note on
+// the stream and launches no second session to file the same causes. A pass that threw before it
+// noted anything leaves only its failure, which the retry answers; a launch that failed is answered
+// once more.
+function is_noted(events: ReadonlyArray<RunEvent>, issue: number): boolean {
+	const notes = overrun_notes(events).filter((note) => note.issue === issue)
+	const failures = notes.filter((note) => is_launch_failure(note)).length
+
+	return failures >= MAX_LAUNCH_FAILURES || notes.some((note) => is_final(note))
+}
+
+// The earlier lanes whose latest note is a launch failure not yet retried; a retry that threw leaves
+// its own note last, so it is not swept up again at every merge after.
+function retried_lanes(events: ReadonlyArray<RunEvent>, issue: number): ReadonlyArray<number> {
+	const latest = new Map(overrun_notes(events).map((note) => [note.issue, note]))
+
+	latest.delete(issue)
+
+	return [...latest.values()]
+		.filter((note) => is_launch_failure(note) && !is_noted(events, note.issue))
+		.map((note) => note.issue)
+}
+
+// A pass that noted the lane before launched nothing it recorded, but it may have commented.
+function is_commented(events: ReadonlyArray<RunEvent>, issue: number): boolean {
+	return overrun_notes(events).some((note) => note.issue === issue)
+}
+
+function net_in(path: string, events: ReadonlyArray<RunEvent>, issue: number): LaneNet {
+	const entries = lane_ledger.read_entries(path)
+	const minutes = lane_net_time.net_minutes(entries, events, issue)
+	const breakdown = lane_breakdown.of(entries, events, issue)
+
+	if (minutes === undefined || breakdown === undefined) {
+		return { kind: 'missing', reason: lane_net_time.missing_reason(entries, issue) }
+	}
+
+	return { kind: 'minutes', minutes, breakdown, entries, is_commented: is_commented(events, issue) }
+}
+
+// The net time of a lane not yet noted, or `undefined` when its note is on the stream already.
+async function net_of(issue: number): Promise<LaneNet | undefined> {
+	const events = await run_event_stream_emit.all_events()
+
+	if (is_noted(events, issue)) return undefined
+
+	const path = await lane_ledger.target()
+
+	return path === undefined ? { kind: 'missing', reason: NO_LEDGER } : net_in(path, events, issue)
+}
+
+// What the session reads, and the four facts it traces each cause to.
+function reading(issue: number, cite: string, minutes: number): string {
+	const directories =
+		lane_breakdown_implement.transcript_directories(issue).join(', ') || 'none found'
+
+	return [
+		`Investigate why lane ${cite} took ${String(minutes)} minutes of net time (dispatch to merge, less`,
+		'its waits on a person and on outages). Leave this checkout as it is: write any file, an issue body',
+		'included, under the system temp directory, and never stage, commit or push.',
+		`Read the lane's transcripts (${directories}), its ship log (\`pnpm josh ship --log ${String(issue)}\`)`,
+		'and the run events (`pnpm josh run:event --from 0`), and find the causes that spent time other than',
+		'waiting. Trace each cause to what can fix it: the span it spent, the signal that led to the wrong call',
+		'or the wait (which command printed what), the `file:line` of the code or document that decided it, and',
+		'where to fix it.',
+	].join(' ')
+}
+
+// One line: `detached_launch` lets a prompt break lines, but a single line keeps the log header whole.
+// The breakdown leads, so the search starts from the longest stage (joshuafolkken/kit#4995).
+function prompt(issue: number, minutes: number, report: Report): string {
+	const reads = reading(issue, issue_cite.plain(issue), minutes)
+	const stages = lane_breakdown_text.line(report)
+
+	return `${stages} ${reads} ${lane_overrun_prompt.handling(issue, minutes)}`
+}
+
+function note_failure(issue: number): (note: string) => void {
+	return (note) => {
+		void run_event_stream_emit.emit(EVENT_KIND.NOTE, run_event_overrun.failed_text(issue, note))
+	}
+}
+
+// A detached investigation session: its prompt, its `env` — the lane marks an overrun's filings count
+// against that lane by, none for the baseline's — the prefix of its log's name, and the note a failed
+// launch leaves.
+interface Investigation {
+	env: Readonly<Record<string, string>>
+	prompt: string
+	log_prefix: string
+	on_failure: (note: string) => void
+}
+
+// What became of the launch, in the words the launch note carries — the overrun's and the baseline
+// investigation's (`lane-baseline.ts`) alike.
+function launch(investigation: Investigation): string {
+	const cwd = process.cwd()
+	const built = agent_argv.resolve_in(investigation.prompt, agent_role_profile.WORKER, cwd)
+
+	if (built.kind === 'rejected') return `not investigated: ${built.note}`
+
+	const request = {
+		argv: built.argv,
+		cwd,
+		env: investigation.env,
+		log_path: stamp_file.stamp_path(investigation.log_prefix, PROJECT_ROOT, LOG_SUFFIX),
+		profile: built.profile,
+	}
+	const result = detached_launch.launch(request, investigation.on_failure)
+
+	return result.kind === 'launched'
+		? run_event_overrun.investigating(result.pid, process_identity.read_start(result.pid))
+		: `not investigated: ${result.note}`
+}
+
+function launched(issue: number, minutes: number, report: Report): string {
+	return launch({
+		env: lane_child_marker.overrun_env_for(String(issue)),
+		prompt: prompt(issue, minutes, report),
+		log_prefix: `${LOG_PREFIX}${String(issue)}-`,
+		on_failure: note_failure(issue),
+	})
+}
+
+type OverranNet = Extract<LaneNet, { kind: 'minutes' }>
+
+// The breakdown goes on the lane's Issue before the session starts, once across the lane's passes; a
+// refused comment costs the comment, not the investigation.
+async function overran_text(issue: number, net: OverranNet): Promise<string> {
+	const report = lane_breakdown_text.report_of(issue, net.breakdown, net.entries)
+	const comment = lane_breakdown_text.comment(issue, net.minutes, report)
+
+	if (!net.is_commented) await git_gh_issue_write.issue_try_comment(String(issue), comment)
+
+	const outcome = launched(issue, net.minutes, report)
+	const longest = lane_breakdown.longest_of(net.breakdown)
+
+	return run_event_overrun.started_text(issue, net.minutes, outcome, longest)
+}
+
+// The note every merged lane leaves: its net minutes at or under the threshold, why it has none, or the
+// launch of its overrun's investigation.
+async function note_text(issue: number, net: LaneNet): Promise<string> {
+	if (net.kind === 'missing') return run_event_overrun.skipped_text(issue, net.reason)
+	// The threshold sets no priority: each filing is ranked by its causes' reducible minutes
+	// (joshuafolkken/kit#4928). `lane:stats` counts the lanes over it on dispatch-to-merge time, not
+	// on this net time.
+	const is_over = lane_tail_stats.is_overrun(net.minutes)
+
+	if (!is_over) return run_event_overrun.within_text(issue, net.minutes)
+
+	// The switch off, an overrun leaves its skip: no breakdown comment and no launch.
+	if (!lane_investigation_switch.is_on()) {
+		return run_event_overrun.skipped_text(issue, DISABLED_REASON)
+	}
+
+	return await overran_text(issue, net)
+}
+
+async function investigate_lane(issue: number): Promise<void> {
+	const net = await net_of(issue)
+
+	if (net === undefined) return
+
+	await run_event_stream_emit.emit(EVENT_KIND.NOTE, await note_text(issue, net))
+}
+
+// Never fails the merge it follows: an error is a note on the stream, not a refused merge.
+async function guarded(issue: number, pass: (issue: number) => Promise<void>): Promise<void> {
+	try {
+		await pass(issue)
+	} catch (error) {
+		note_failure(issue)(detached_launch.note_of(error))
+	}
+}
+
+// The merged lane, then each earlier lane whose launch failed once.
+async function investigate_with_retries(issue: number): Promise<void> {
+	await investigate_lane(issue)
+	const retried = retried_lanes(await run_event_stream_emit.all_events(), issue)
+
+	for (const lane of retried) {
+		// eslint-disable-next-line no-await-in-loop -- one pass at a time appends to the stream, as the merged lane's did
+		await guarded(lane, investigate_lane)
+	}
+}
+
+// With the switch off a lane still notes its net minutes, which `run:board` draws; no earlier lane is
+// retried.
+async function investigate(issue: number): Promise<void> {
+	const pass = lane_investigation_switch.is_on() ? investigate_with_retries : investigate_lane
+
+	await guarded(issue, pass)
+}
+
+const lane_overrun = { investigate, launch }
+
+export type { Investigation }
+export { lane_overrun }

package/scripts/lane/lane-paths.ts

@@ -57,6 +57,16 @@ function is_lane_root(directory: string, environment: LaneEnvironment): boolean
 	return DEFAULT_LANE_ROOT_PATTERN.test(path.basename(directory))
 }
 
+// Claude Code's own worktrees (`EnterWorktree`, an `isolation: "worktree"` subagent) sit at
+// `<checkout>/.claude/worktrees/<name>`, and a hook launched in one runs there
+// (joshuafolkken/kit#4617). The session is still the one its checkout started, so a directory under
+// one reads as the checkout that holds it.
+const CLAUDE_WORKTREES_PATTERN = /[/\\]\.claude[/\\]worktrees[/\\][^/\\]+(?:[/\\].*)?$/u
+
+function checkout_of(directory: string): string {
+	return directory.replace(CLAUDE_WORKTREES_PATTERN, '')
+}
+
 // **The inverse of `lane_directory`, and the one lane test that needs no git.** `lane_registry`
 // answers the same question authoritatively by parsing `git worktree list`, but that read is
 // asynchronous and a `PreToolUse` guard is synchronous by contract — so a guard that has to know
@@ -71,7 +81,7 @@ function lane_issue_of(
 	directory: string,
 	environment: LaneEnvironment = process.env,
 ): string | undefined {
-	const resolved = path.resolve(directory)
+	const resolved = checkout_of(path.resolve(directory))
 	const issue = path.basename(resolved)
 
 	if (!issue_number_shape.ISSUE_NUMBER_PATTERN.test(issue)) return undefined
@@ -79,6 +89,17 @@ function lane_issue_of(
 	return is_lane_root(path.dirname(resolved), environment) ? issue : undefined
 }
 
+// The lane `directory` (this process's own by default) sits in, as a number; `undefined` outside a
+// lane — the `issue` a ledger row written from inside a lane carries.
+function issue_here(
+	directory: string = process.cwd(),
+	environment: LaneEnvironment = process.env,
+): number | undefined {
+	const lane = lane_issue_of(directory, environment)
+
+	return lane === undefined ? undefined : Number(lane)
+}
+
 function lane_branch(issue: string): string {
 	return `${issue}${LANE_BRANCH_SUFFIX}`
 }
@@ -98,8 +119,10 @@ const lane_paths = {
 	LANE_BRANCH_SUFFIX,
 	LANE_ROOT_KEY,
 	SEAT_LOCK_DIR,
+	checkout_of,
 	default_lane_root,
 	is_lane_entry,
+	issue_here,
 	lane_branch,
 	lane_directory,
 	lane_issue_of,

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

@@ -4,6 +4,7 @@ import { issue_cite } from '#scripts/issue/issue-cite'
 import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { run_event_stream } from '#scripts/run/event/run-event-stream'
 import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
+import { lane_ledger_write } from './lane-ledger-write'
 import { lane_pause, type LaneSignalled } from './lane-pause'
 import type { LaneProcesses } from './lane-reap'
 import { lane_registry } from './lane-registry'
@@ -14,7 +15,8 @@ import { lane_state } from './lane-state'
 // caller never takes a pause that stopped nothing as done — a detached resident signalled alone counts
 // as nothing. A lane whose detached processes could not be read exits non-zero too, since a resume
 // may have left one of them stopped. A lane whose child was signalled has the change written to its state record and to the
-// run's event stream, so who halted it is on record.
+// run's event stream, so who halted it is on record, and to the lane ledger, so `lane:stats` leaves the
+// stopped time out of the lane's implement sub-stages (joshuafolkken/kit#5168).
 
 const ARGV_OFFSET = 2
 const SUCCESS_EXIT_CODE = 0
@@ -73,6 +75,7 @@ async function record(verb: Verb, issue: string): Promise<void> {
 	const command = `lane:${verb}`
 
 	await lane_state.record_change({ issue, state: VERBS[verb].state, command })
+	await lane_ledger_write.record_lane_state({ issue: Number(issue), state: VERBS[verb].state })
 	await run_event_stream_emit.emit(
 		run_event_stream.EVENT_KIND.LANE_STATE,
 		`${issue_cite.plain(issue)} ${VERBS[verb].done} by ${command}`,

package/scripts/lane/lane-paused-spans.ts

@@ -0,0 +1,97 @@
+import {
+	lane_ledger,
+	type DispatchEntry,
+	type LaneStateChangeEntry,
+	type LedgerEntry,
+} from './lane-ledger'
+
+// The spans each lane stood paused, read off the `lane-state` lines `lane:pause` and `lane:resume`
+// append to the ledger (joshuafolkken/kit#5168). A SIGSTOP leaves the call in flight on the clock, so a
+// measurement of a lane's time takes its overlap with these out: `lane:pause --all` once put seven
+// hours into one plan call and one check call.
+//
+// **A pause opens a span, the lane's next resume or dispatch closes it** — `lane:restart` and a
+// re-dispatch start a fresh child without a resume; a pause with neither yet stays open, and a
+// resume with no pause before it closes nothing.
+
+const PAUSED = 'paused'
+const LANE_ISSUE_PATTERN = /-(?<issue>\d+)$/u
+
+interface PausedSpan {
+	from_ms: number
+	to_ms: number
+}
+
+// Each lane's paused spans, by issue number.
+type PausedSpans = ReadonlyMap<number, ReadonlyArray<PausedSpan>>
+
+interface Walk {
+	spans: Array<PausedSpan>
+	open_ms: number | undefined
+}
+
+// A ledger line that opens or closes a lane's paused span.
+type Change = LaneStateChangeEntry | DispatchEntry
+
+const NONE: ReadonlyArray<PausedSpan> = []
+
+function is_change(entry: LedgerEntry): entry is Change {
+	return entry.kind === lane_ledger.KIND.LANE_STATE || entry.kind === lane_ledger.KIND.DISPATCH
+}
+
+function is_pause(change: Change): boolean {
+	return change.kind === lane_ledger.KIND.LANE_STATE && change.state === PAUSED
+}
+
+function step(walk: Walk, change: Change): Walk {
+	const at_ms = Date.parse(change.at)
+
+	if (is_pause(change)) return { spans: walk.spans, open_ms: walk.open_ms ?? at_ms }
+	if (walk.open_ms === undefined) return walk
+
+	return { spans: [...walk.spans, { from_ms: walk.open_ms, to_ms: at_ms }], open_ms: undefined }
+}
+
+// One lane's changes, oldest first, folded into its spans.
+function spans_of(changes: ReadonlyArray<Change>): Array<PausedSpan> {
+	let walk: Walk = { spans: [], open_ms: undefined }
+
+	for (const change of changes) walk = step(walk, change)
+	if (walk.open_ms === undefined) return walk.spans
+
+	return [...walk.spans, { from_ms: walk.open_ms, to_ms: Infinity }]
+}
+
+function by_lane(entries: ReadonlyArray<LedgerEntry>): PausedSpans {
+	const changes = entries
+		.filter((entry) => is_change(entry))
+		.toSorted((left, right) => Date.parse(left.at) - Date.parse(right.at))
+	const issues = [...new Set(changes.map((change) => change.issue))]
+
+	return new Map(
+		issues.map((issue) => [issue, spans_of(changes.filter((change) => change.issue === issue))]),
+	)
+}
+
+// The spans of the lane a transcript directory (`<lane-root-slug>-<issue>`) belongs to.
+function of_lane(spans: PausedSpans, lane: string): ReadonlyArray<PausedSpan> {
+	const issue = LANE_ISSUE_PATTERN.exec(lane)?.groups?.['issue']
+
+	return issue === undefined ? NONE : (spans.get(Number(issue)) ?? NONE)
+}
+
+// How much of `from_ms`…`to_ms` the spans cover.
+function overlap_ms(spans: ReadonlyArray<PausedSpan>, from_ms: number, to_ms: number): number {
+	let sum = 0
+
+	for (const span of spans) {
+		sum += Math.max(0, Math.min(to_ms, span.to_ms) - Math.max(from_ms, span.from_ms))
+	}
+
+	return sum
+}
+
+const lane_paused_spans = { by_lane, of_lane, overlap_ms }
+
+export type { PausedSpan, PausedSpans }
+export { lane_paused_spans }

package/scripts/lane/lane-plan-check.ts

@@ -0,0 +1,207 @@
+import { auto_ok_cli } from '#scripts/auto-ok/auto-ok-cli'
+import { backlog_overlap, type Clash } from '#scripts/backlog/backlog-overlap'
+import { backlog_plan_comment } from '#scripts/backlog/backlog-plan-comment'
+import type { OpenIssueData } from '#scripts/git/git-schemas'
+import { has_any_label, IN_PROGRESS_LABEL } from '#scripts/issue/issue-labels'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { session_cite } from '#scripts/issue/session-cite'
+import { run_hold_cli } from '#scripts/run/hold/run-hold-cli'
+import { lane_plan, type LanePlan } from './lane-plan'
+import { lane_yield, type YieldAt } from './lane-yield'
+
+// The check `josh lane:plan <issue> <path>...` runs (`lane-plan-cli.ts`) — record the files a lane child
+// plans to edit, and answer once whether a running lane that planned earlier declares or plans one of
+// them (joshuafolkken/kit#4864).
+//
+// **The check happens before the first edit**, so a conflict the bodies did not show is met while the
+// later lane has nothing to throw away, not at its ship. **A lane that finds a holder gives its lane
+// back** rather than waiting for the holder to end (joshuafolkken/kit#4926): polling kept the seat taken
+// while nothing moved, which made two lanes one. It notes its yield (`lane-yield.ts`), keeps its plan as
+// yielded, releases its hold, prints `yield` and the child ends; the issue is offered again once the
+// holder's lane ends. A document under `docs/` is never a clash (`backlog-overlap.ts` →
+// `is_shared_document`).
+//
+// **`--probe` answers the same question and records nothing** (joshuafolkken/kit#5211) — no plan, no
+// yield, no release. **`run:entry` gives the lane back at the entry** in a lane child, before any
+// reading, on the paths dispatch gated on (`yield_at_entry`), so a holder that planned them since
+// dispatch takes the lane back before the investigation the later `lane:plan` would have thrown away.
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const YIELD_EXIT_CODE = 2
+const RELEASE_FLAG = '--release'
+const RUNNING = new Set([IN_PROGRESS_LABEL])
+const UNREAD = 'unread'
+
+// What the overlap check found: the clash, none, or a listing it could not read.
+type Probe = Clash | typeof UNREAD | undefined
+
+function plan_of(argv: ReadonlyArray<string>, now: Date): LanePlan | undefined {
+	const [issue = '', ...paths] = argv
+
+	const claims = [...backlog_overlap.path_claims(paths)]
+
+	if (!issue_number_shape.is_issue_number(issue) || claims.length === 0) return undefined
+
+	return { issue: Number(issue), paths: claims, planned_at: now.toISOString() }
+}
+
+// The opted-in listing — the running lanes carry the pickup label, so it holds their bodies.
+async function opted_in(): Promise<ReadonlyArray<OpenIssueData> | undefined> {
+	const read = await auto_ok_cli.fetch_opted_in()
+
+	return read.kind === 'read' ? read.issues : undefined
+}
+
+function running_of(issues: ReadonlyArray<OpenIssueData>): ReadonlyArray<OpenIssueData> {
+	return issues.filter((issue) => has_any_label(issue.labels, RUNNING))
+}
+
+function clash_among(
+	plan: LanePlan,
+	issues: ReadonlyArray<OpenIssueData>,
+	directory: string,
+): Clash | undefined {
+	const declared = lane_plan.with_plans(backlog_overlap.declared_of(issues), directory)
+
+	return lane_plan.clash_of(plan, declared, directory)
+}
+
+function overlap_text(issue: number, clash: Clash): string {
+	const holder = session_cite.issue(clash.holder)
+
+	return `${session_cite.issue(issue)}'s planned \`${clash.path}\` overlaps \`${clash.claimed}\`, which ${holder} declares or plans`
+}
+
+// The yield goes on the stream before the child is told to end, so `run:merge` books it `yielded`. The
+// plan is kept as yielded (`lane_plan.release`) and the child's hold released, so it can end with no
+// edit; `yield` is printed last, after the release's own verdict.
+async function give_back(
+	plan: LanePlan,
+	clash: Clash,
+	directory: string,
+	at: YieldAt,
+): Promise<number> {
+	const overlap = overlap_text(plan.issue, clash)
+
+	lane_plan.record({ ...plan, yielded: true }, directory)
+	await lane_yield.record_yield(plan.issue, overlap, at)
+	await run_hold_cli.run([RELEASE_FLAG, String(plan.issue)])
+	console.error(
+		`${overlap}, so it gives its lane back: end the session now, with no edit — \`run:merge\` closes the lane, and the issue is offered again once that lane ends.`,
+	)
+	console.info('yield')
+
+	return YIELD_EXIT_CODE
+}
+
+function clear_answer(): number {
+	console.info('clear')
+
+	return SUCCESS_EXIT_CODE
+}
+
+function clear(plan: LanePlan, directory: string): number {
+	lane_plan.record({ ...plan, cleared: true, yielded: undefined }, directory)
+
+	return clear_answer()
+}
+
+// An unread listing proves no holder absent, so it holds the edit back for one more ask.
+function unread(): number {
+	console.error(auto_ok_cli.UNREADABLE_MESSAGE)
+	console.info('wait')
+
+	return FAILURE_EXIT_CODE
+}
+
+// The overlap check alone, writing nothing — what `--probe` answers and `check_plan` acts on.
+async function probe(plan: LanePlan, directory: string): Promise<Probe> {
+	const issues = await opted_in()
+
+	return issues === undefined ? UNREAD : clash_among(plan, running_of(issues), directory)
+}
+
+async function check_plan(plan: LanePlan, directory: string): Promise<number> {
+	lane_plan.record(plan, directory)
+	const found = await probe(plan, directory)
+
+	if (found === UNREAD) return unread()
+
+	return found === undefined
+		? clear(plan, directory)
+		: await give_back(plan, found, directory, 'summary')
+}
+
+// `--probe`'s answer: the same tokens and exit codes as the plan's, with nothing written.
+async function probe_answer(plan: LanePlan, directory: string): Promise<number> {
+	const found = await probe(plan, directory)
+
+	if (found === UNREAD) return unread()
+	if (found === undefined) return clear_answer()
+
+	console.error(`${overlap_text(plan.issue, found)}.`)
+	console.info('yield')
+
+	return YIELD_EXIT_CODE
+}
+
+// A lane that plans again — after a yield, or to add a file — keeps the place in line its first plan
+// took: a fresh time would hand the files it already holds to a lane that planned after it. A yield
+// stays marked until the plan clears, so a check the listing could not answer keeps the plan its lane
+// yielded on.
+function placed(plan: LanePlan, directory: string): LanePlan {
+	const recorded = lane_plan.read(plan.issue, directory)
+	if (recorded === undefined) return plan
+
+	return { ...plan, planned_at: recorded.planned_at, yielded: recorded.yielded }
+}
+
+// The paths `issue` declares in the scope dispatch gated on — its recorded plan, else its plan comment,
+// else its body (`backlog-plan-comment.ts`) — read off the same listing the probe reads the holders from.
+async function entry_plan(
+	issue: number,
+	issues: ReadonlyArray<OpenIssueData>,
+	directory: string,
+): Promise<LanePlan | undefined> {
+	const own = issues.filter((candidate) => candidate.number === issue)
+	const declared = await backlog_plan_comment.declared_of(own, directory)
+	const plan = plan_of([String(issue), ...(declared.get(issue) ?? [])], new Date())
+
+	return plan === undefined ? undefined : placed(plan, directory)
+}
+
+async function entry_yield(
+	issue: number,
+	issues: ReadonlyArray<OpenIssueData>,
+	directory: string,
+): Promise<boolean> {
+	const plan = await entry_plan(issue, issues, directory)
+	const found = plan === undefined ? undefined : clash_among(plan, running_of(issues), directory)
+
+	if (plan === undefined || found === undefined) return false
+
+	await give_back(plan, found, directory, 'entry')
+
+	return true
+}
+
+// **The entry probe** `run:entry` runs in a lane child before the investigation: a clash gives the lane back
+// there, noted `at: entry`, the way `lane:plan` would after the summary. A clear answer, an unread
+// listing or no declared path writes nothing — the later `lane:plan` still checks at the first edit.
+async function yield_at_entry(issue: number, directory: string = process.cwd()): Promise<boolean> {
+	const issues = await opted_in()
+
+	return issues === undefined ? false : await entry_yield(issue, issues, directory)
+}
+
+const lane_plan_check = {
+	YIELD_EXIT_CODE,
+	check_plan,
+	placed,
+	plan_of,
+	probe_answer,
+	yield_at_entry,
+}
+
+export { lane_plan_check }