@joshuafolkken/kit 1.1166.0 → 1.1229.0

package/scripts/rules/wip-cap.ts

@@ -0,0 +1,63 @@
+import { bash_triggers } from './bash-triggers'
+import { shell_segments } from './shell-segments'
+
+// The trigger and the delivered text behind the `wip-cap` row of `delivered-rules.ts`, moved out of
+// the enumeration so the list stays a list (joshuafolkken/kit#3264).
+
+// The whole of the WIP cap, in the shape a refusal can carry: the count, the refusal, the two
+// exemptions and the three tests that decide the second one. The three tests are spelled out rather
+// than named, because a delivery that said only "an interrupt is exempt" would hand the deciding back
+// to judgement at exactly the moment nothing else is open to read (joshuafolkken/kit#1518).
+// `WIP_CAP` is the number's single source; `wip-cap.md` states it once and a test pins the two equal.
+const WIP_CAP = 30
+const WIP_CAP_REASON =
+	`⛔ backlog WIP cap: \`pnpm josh issue:file\` counts the target repository's open Issues before filing. With more than ${String(WIP_CAP)} ` +
+	'open, close one first; nothing honestly closable means do not file — the command holds such a filing. ' +
+	'Two filings are exempt and proceed while stating the overage — one the run is blocked by (`--over-cap`, ' +
+	'or the `tier-a` / `split` route), and an interrupt (`--route interrupt`), decided by three tests rather ' +
+	'than judgement: a verification answers wrongly, a documented workflow cannot complete, or data is lost ' +
+	'or written outside the repository. Meeting none of the three, the finding is discretionary and waits. ' +
+	'Both procedures are in `prompts/collaboration-workflow/wip-cap.md`. Reissue this call and let the ' +
+	'command count — it fires once per run and cannot repeat on the call in hand.'
+
+// **Keeping the WIP cap is counting the open Issues**, which is the one act the rule asks for before
+// a filing.
+//
+// **It has to be Issues, open, and a listing — all three, in one segment.** A pattern that took any
+// of them alone scored `gh pr list --state open` and `epic:bundle`'s candidate search as the count,
+// and those inflate exactly the ratio the retirement decision reads. `gh issue list` alone is not
+// enough either: the cap is about *open* Issues, and a listing that does not say so is some other
+// question. Segment-wise like the comments predicate, so a spelling quoted inside a filing's body
+// is not read as the count that filing skipped.
+const ISSUE_LISTING = /^gh\s+(?:-{1,2}[\w-]+(?:[= ]\S+)?\s+)*issue\s+list\b/u
+const ISSUES_QUERY = /repos\/[^\s'"]*\/issues\?[^\s'"]*state=open/u
+const OPEN_STATE = /--state[= ]open|state=open/u
+// **A label filter makes it a different question.** `gh issue list --label epic --state open` and
+// `…/issues?labels=epic&state=open` ask which epics are open, which is what `epic:bundle` and the
+// Issue template do; counting either as the WIP count would credit the cap as kept by a run that
+// never counted the backlog. The residual the pattern cannot separate is named in
+// `docs/josh-commands.md`: the inventory command in the `diag` skill is byte-identical to a hand count
+// of the backlog, so no pattern can tell those two apart.
+const LABEL_FILTER = /--label\b|[?&]labels=/u
+
+function counts_open_issues(command: string): boolean {
+	return shell_segments.segments_of(command).some((segment) => {
+		if (LABEL_FILTER.test(segment)) return false
+
+		return (ISSUE_LISTING.test(segment) && OPEN_STATE.test(segment)) || ISSUES_QUERY.test(segment)
+	})
+}
+
+// The enumeration row itself, so `delivered-rules.ts` spreads one entry rather than restating the
+// trigger and reason it already single-sources here. Once per run: the refusal changes what the run
+// knows, so the reissue is let through.
+const ROW = {
+	id: 'wip-cap',
+	is_trigger: bash_triggers.on_bash_command(bash_triggers.is_issue_filing),
+	reason: WIP_CAP_REASON,
+	keeps: bash_triggers.on_bash_command(counts_open_issues),
+}
+
+const wip_cap = { ROW, WIP_CAP, WIP_CAP_REASON }
+
+export { wip_cap }

package/scripts/run/{run-carry-args.ts → carry/run-carry-args.ts}

@@ -1,6 +1,6 @@
 import { cli_flags } from '#scripts/lib/cli-flags'
+import { run_issue_number } from '#scripts/run/run-issue-number'
 import { run_carry, type CarryChange, type CarryClaimRequest, type CarryOwner } from './run-carry'
-import { run_issue_number } from './run-issue-number'
 
 // The argument half of `josh run:carry`. It sat inside `run-carry-cli.ts` until the ownership answers
 // joshuafolkken/kit#1722 added took that file to 96% of the 300-line limit, and the seam it split on
@@ -9,6 +9,7 @@ import { run_issue_number } from './run-issue-number'
 
 const NO_INCREMENT = 0
 const ONE_CUT = 1
+const ONE_MERGE = 1
 // The four request groups below are mutually exclusive, so more than one of them named in a single
 // invocation is a usage error rather than an order to guess.
 const ONE_GROUP = 1
@@ -22,7 +23,7 @@ const MIN_PID = 1
 // cannot advance a budget that is no longer its own. `--end` alone accepts it and ignores it, and a
 // usage line that offered it there would be promising an ownership check nothing performs.
 const USAGE =
-	'Usage: josh run:carry [--json] | --begin <invocation> [--owner <pid>] | --resume <invocation> [--owner <pid>] | (--cut | --merged <count> | --filed <count> | --done <issue> | --retrospective --summary <text>) [--owner <pid>] | --end [--stopped <reason>]'
+	'Usage: josh run:carry [--json] | --begin <invocation> [--owner <pid>] | --resume <invocation> [--owner <pid>] | (--cut | --merged <issue> | --filed <count> | --done <issue> | --retrospective --summary <text>) [--owner <pid>] | --end [--stopped <reason>]'
 
 const OPTIONS = {
 	begin: { type: 'string' },
@@ -89,12 +90,12 @@ function to_count(value: OptionValue): number | undefined {
 	return COUNT_PATTERN.test(text) ? Number(text) : undefined
 }
 
-// **`--done` names an issue, so it is checked as one and not as a count.** The shape is
-// `run-issue-number.ts`'s, which already refuses `0` and a leading zero — the same rule the `run:*`
+// **`--done` and `--merged` name an issue, so each is checked as one and not as a count.** The shape
+// is `run-issue-number.ts`'s, which already refuses `0` and a leading zero — the same rule the `run:*`
 // commands interpolate a number under, imported rather than restated. Absent is an empty object rather
 // than a zero: there is no issue to record, which is a different fact from recording issue zero. A
-// present-but-malformed value invalidates the whole invocation, exactly as a bad `--merged` does.
-function to_done(value: OptionValue): Pick<CarryChange, 'done'> | undefined {
+// present-but-malformed value is `undefined`, which invalidates the whole invocation.
+function to_issue(value: OptionValue): { issue?: number } | undefined {
 	const text = cli_flags.string_of(value)
 
 	if (text === undefined) return {}
@@ -106,7 +107,30 @@ function to_done(value: OptionValue): Pick<CarryChange, 'done'> | undefined {
 	// The pattern is anchored on digits and bounds nothing, so the magnitude check is separate — the
 	// same shape `backlog_budget_cli.to_count` ends with. A number past the safe range would be
 	// recorded as a different number and never match anything in `remaining`.
-	return Number.isSafeInteger(issue) ? { done: issue } : undefined
+	return Number.isSafeInteger(issue) ? { issue } : undefined
+}
+
+function to_done(value: OptionValue): Pick<CarryChange, 'done'> | undefined {
+	const parsed = to_issue(value)
+
+	if (parsed === undefined) return undefined
+
+	return parsed.issue === undefined ? {} : { done: parsed.issue }
+}
+
+// **`--merged` names the issue that merged, never a count** (joshuafolkken/kit#3296). A bare count
+// could not be matched against `merged_issues`, so a parent that counted a merge by hand and the
+// driver's `run:merge` for the same issue added two for one merge. Naming the issue makes the hand
+// count the same change `run:merge` applies — one merge plus its number — so `apply_change`'s
+// duplicate check holds whichever of the two arrives first.
+function to_merged(value: OptionValue): Pick<CarryChange, 'merged' | 'merged_issue'> | undefined {
+	const parsed = to_issue(value)
+
+	if (parsed === undefined) return undefined
+
+	return parsed.issue === undefined
+		? { merged: NO_INCREMENT }
+		: { merged: ONE_MERGE, merged_issue: parsed.issue }
 }
 
 // The two boolean marks in the counting group — `--cut` and `--retrospective` — as the partial the
@@ -119,18 +143,18 @@ function to_marks(values: ParsedValues): Pick<CarryChange, 'cuts' | 'retrospecti
 }
 
 function to_change(values: ParsedValues): CarryChange | undefined {
-	const merged = to_count(values.merged)
+	const merged = to_merged(values.merged)
 	const filed = to_count(values.filed)
 	const done = to_done(values.done)
 
 	if (merged === undefined || filed === undefined || done === undefined) return undefined
 
-	return { merged, filed, ...to_marks(values), ...done }
+	return { ...merged, filed, ...to_marks(values), ...done }
 }
 
-// **A counting flag is what makes a count, never the sum of one.** `--merged 0` is a run reporting
-// that a wave merged nothing, and reading it as a bare read would answer `none` with exit 0 against
-// a record that is not there — the silent zero `docs/josh-commands.md` says exits 1.
+// **A counting flag is what makes a count, never the sum of one.** `--filed 0` is a run reporting
+// that it filed nothing, and reading it as a bare read would answer `none` with exit 0 against a
+// record that is not there — the silent zero `docs/josh-commands.md` says exits 1.
 function has_count(values: ParsedValues): boolean {
 	return (
 		values.cut === true ||
@@ -189,7 +213,7 @@ function is_summary_paired(values: ParsedValues): boolean {
 
 // The counting group, split out so the shape below stays a flat list of exits. The summary rides along
 // only when it is there — guaranteed paired with `--retrospective` by `is_summary_paired` — so a plain
-// `--merged` count never carries one.
+// `--merged` never carries one.
 function to_count_request(values: ParsedValues, owner: CarryOwner): Request | undefined {
 	const change = to_change(values)
 

package/scripts/run/{run-carry-change.ts → carry/run-carry-change.ts}

@@ -18,7 +18,9 @@ function next_merged_issues(
 ): ReadonlyArray<number> | undefined {
 	if (issue === undefined) return carry.merged_issues
 
-	return [...(carry.merged_issues ?? []), issue]
+	const current = carry.merged_issues ?? []
+
+	return current.includes(issue) ? current : [...current, issue]
 }
 
 function is_duplicate_merge(carry: RunCarry, change: CarryChange): boolean {
@@ -27,6 +29,24 @@ function is_duplicate_merge(carry: RunCarry, change: CarryChange): boolean {
 	return issue !== undefined && carry.merged_issues?.includes(issue) === true
 }
 
+// Whether a change carries anything besides its merge — a filing, a cut, a streak step, a done issue
+// or the retrospective mark.
+function has_other_change(change: CarryChange): boolean {
+	const amounts = [change.filed, change.cuts, change.failures, change.outages]
+	const has_amount = amounts.some((amount) => (amount ?? NO_INCREMENT) > NO_INCREMENT)
+
+	return has_amount || change.done !== undefined || change.retrospective === true
+}
+
+// **A duplicate merge drops only the merge** (joshuafolkken/kit#3296): `--merged <issue>` may ride
+// beside `--filed` or `--done` in one call, and those are still increments the record has not seen.
+// Only a duplicate carrying nothing else leaves the record untouched, which is `undefined` here.
+function effective_change(carry: RunCarry, change: CarryChange): CarryChange | undefined {
+	if (!is_duplicate_merge(carry, change)) return change
+
+	return has_other_change(change) ? { ...change, merged: NO_INCREMENT } : undefined
+}
+
 function next_counts(
 	carry: RunCarry,
 	change: CarryChange,
@@ -47,18 +67,20 @@ function apply_change(
 	change: CarryChange,
 	now: Date = new Date(),
 ): RunCarry {
-	if (is_duplicate_merge(carry, change)) return carry
+	const effective = effective_change(carry, change)
+
+	if (effective === undefined) return carry
 
-	const streak = run_carry_streak.next_state(carry, change, now)
+	const streak = run_carry_streak.next_state(carry, effective, now)
 	const next: RunCarry = {
 		...carry,
-		...next_counts(carry, change),
-		merged_issues: next_merged_issues(carry, change.merged_issue),
+		...next_counts(carry, effective),
+		merged_issues: next_merged_issues(carry, effective.merged_issue),
 		failures: streak.failures,
 		outages: streak.outages,
 		last_outage_at: streak.last_outage_at,
-		done: next_done(carry, change.done),
-		retrospective: change.retrospective === true || carry.retrospective,
+		done: next_done(carry, effective.done),
+		retrospective: effective.retrospective === true || carry.retrospective,
 	}
 
 	stamp_file.write_stamp(target, next)

package/scripts/run/{run-carry-cli.ts → carry/run-carry-cli.ts}

@@ -2,6 +2,9 @@
 import { fileURLToPath } from 'node:url'
 import { cost_cli } from '#scripts/cost-runtime/cost-cli'
 import { cost_verdict } from '#scripts/cost-runtime/cost-verdict'
+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 { run_stop_notify } from '#scripts/run/run-stop-notify'
 import {
 	run_carry,
 	type CarryClaim,
@@ -12,9 +15,6 @@ import {
 import { run_carry_args, type CountRequest, type Request } from './run-carry-args'
 import { run_carry_conversation } from './run-carry-conversation'
 import { run_carry_stash } from './run-carry-stash'
-import { run_event_stream } from './run-event-stream'
-import { run_event_stream_emit } from './run-event-stream-emit'
-import { run_stop_notify } from './run-stop-notify'
 
 // `josh run:carry` — the record that carries one invocation's budget across its own session cuts
 // (joshuafolkken/kit#1714). A `backlogrun` begins it, counts a merge and a filing into it, marks each
@@ -303,9 +303,7 @@ function blocked_count(
 	request: CountRequest,
 	is_json: boolean,
 ): number | undefined {
-	if (run_carry.is_count_refused(carry, request.owner)) {
-		return report_count_refused(carry, is_json)
-	}
+	if (run_carry.is_count_refused(carry, request.owner)) return report_count_refused(carry, is_json)
 
 	if (is_cut_count(request) && run_carry.is_at_cut_cap(carry)) {
 		return report_cut_capped(carry, is_json)

package/scripts/run/{run-carry.ts → carry/run-carry.ts}

@@ -2,10 +2,10 @@ import { backlog_budget } from '#scripts/backlog/backlog-budget'
 import { git_command } from '#scripts/git/git-command'
 import { process_identity } from '#scripts/josh/process-identity'
 import { stamp_file } from '#scripts/josh/stamp-file'
+import { run_invocation } from '#scripts/run/run-invocation'
 import { z } from 'zod'
 import { run_carry_change } from './run-carry-change'
 import { run_carry_conversation } from './run-carry-conversation'
-import { run_invocation } from './run-invocation'
 
 // joshuafolkken/kit#1714: a `backlogrun` declares a budget — `--max`, `--idle` and the 8-hour
 // whole-run bound — and then loses all of it at the session cut, because the cut ends the session and
@@ -480,15 +480,20 @@ function busy_message(carry: RunCarry): string {
 	return `A live run holds this budget — ${describe_carry(carry)}, owner pid ${String(carry.owner_pid)} still running. Nothing was established. Wait for that run, or end its record with \`${END_COMMAND}\` once you know it is over.`
 }
 
+// The adoption command, shared by the standing refusal and the judgment wake's hand-off.
+// **`--owner "$PPID"` is part of the command, not an optional extra.** An adoption made without it
+// leaves the record declaring no owner, and from then on every second parent reads it as not provably
+// live and is answered `standing` rather than `busy` — the ownership defense degrading silently
+// through the very message that recommends the command.
+function claim_command(invocation: string): string {
+	return `${RESUME_COMMAND} "${invocation}" ${OWNER_ARGUMENT}`
+}
+
 // The record's owner is gone and no cut handed it off — the crashed run, and the same command
 // retyped over it. Both ways out are named, because which one is right is the reader's to say and
 // not this command's to guess.
-// **`--owner "$PPID"` is part of the command it prints, not an optional extra.** An adoption made
-// without it leaves the record declaring no owner, and from then on every second parent reads it as
-// not provably live and is answered `standing` rather than `busy` — the ownership defense degrading
-// silently through the very message that recommends the command.
 function standing_message(carry: RunCarry): string {
-	return `A run record is standing here that no cut handed off — ${describe_carry(carry)}. Nothing was established. Carry that budget with \`${RESUME_COMMAND} "${carry.invocation}" ${OWNER_ARGUMENT}\`, or discard it with \`${END_COMMAND}\` and begin again.`
+	return `A run record is standing here that no cut handed off — ${describe_carry(carry)}. Nothing was established. Carry that budget with \`${claim_command(carry.invocation)}\`, or discard it with \`${END_COMMAND}\` and begin again.`
 }
 
 // The count refusal reads differently by cause: a record awaiting its successor, or one a successor
@@ -535,6 +540,7 @@ const run_carry = {
 	begin_carry,
 	busy_message,
 	carry_path,
+	claim_command,
 	classify,
 	classify_claim,
 	count_refused_message,

package/scripts/run/{run-cut-args.ts → cut/run-cut-args.ts}

@@ -1,5 +1,5 @@
 import { cli_flags } from '#scripts/lib/cli-flags'
-import { run_issue_number } from './run-issue-number'
+import { run_issue_number } from '#scripts/run/run-issue-number'
 
 // `josh run:cut` turns its `argv` into one of four requests. The contract mirrors `run-carry-args.ts`:
 // parsing lives here, acting on the record lives in `run-cut-cli.ts`, and a malformed command line is

package/scripts/run/{run-cut-cli.ts → cut/run-cut-cli.ts}

@@ -6,12 +6,12 @@ import { git_command } from '#scripts/git/git-command'
 import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
 import { lane_relaunch } from '#scripts/lane/lane-relaunch'
 import { openai_lane_supervisor } from '#scripts/lane/openai-lane-supervisor'
+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 { run_cut, type CutState, type RunCut } from './run-cut'
 import { run_cut_args, type Request } from './run-cut-args'
 import { run_cut_handoff } from './run-cut-handoff'
 import { run_cut_report } from './run-cut-report'
-import { run_event_stream } from './run-event-stream'
-import { run_event_stream_emit } from './run-event-stream-emit'
 
 // `josh run:cut` — the record that lets a lane child end its process before the gate and a fresh one
 // resume from it (joshuafolkken/kit#1839). `run:cut <N>` writes the record and relaunches a fresh
@@ -60,7 +60,7 @@ const {
 } = run_cut_report
 
 // **The pre-gate cut is conditional on the same statistic the implementation-phase cut reads**
-// (joshuafolkken/kit#2312). `cost_cli.session_verdict` prices the recent `RECENT_REQUEST_WINDOW`
+// (joshuafolkken/kit#2312). `cost_cli.session_verdict` prices the newest request
 // against `CONTEXT_CUT_THRESHOLD`, so no second threshold is introduced — an `under` session skips the
 // cut, and an unmeasurable one keeps the old unconditional cut as the safety net joshuafolkken/kit#1933
 // relies on. Only the pre-gate phase is checked here; the implementation-phase caller gates its own

package/scripts/run/{run-cut-report.ts → cut/run-cut-report.ts}

@@ -14,7 +14,7 @@ const RESUME_VERDICT = 'resume'
 // re-reading the record.
 const RESUME_IMPL_VERDICT = 'resume-impl'
 const FRESH_VERDICT = 'fresh'
-// The recent-window context is under the shared cut threshold, so the pre-gate cut was not worth its
+// The current context is under the shared cut threshold, so the pre-gate cut was not worth its
 // resume and nothing was cut (joshuafolkken/kit#2312). A benign, non-failing answer: the run carries
 // on to the gate itself, exactly as `not-a-lane` does.
 const UNDER_THRESHOLD_VERDICT = 'under-threshold'
@@ -111,7 +111,7 @@ function refuse_unready(state: CutState): number {
 // relaunch costs more than it saves; the current process carries the run on to the gate uncut.
 function report_under_threshold(): number {
 	console.error(
-		'The recent-window context is under the shared cut threshold, so nothing was cut; a resume would cost more than the accumulation it would drop. Continue to the gate.',
+		'The current context is under the shared cut threshold, so nothing was cut; a resume would cost more than the accumulation it would drop. Continue to the gate.',
 	)
 
 	return report(UNDER_THRESHOLD_VERDICT, SUCCESS_EXIT_CODE)

package/scripts/run/{run-cut.ts → cut/run-cut.ts}

@@ -5,9 +5,9 @@ import { git_command } from '#scripts/git/git-command'
 import { git_common_directory } from '#scripts/git/git-common-directory'
 import { stamp_file } from '#scripts/josh/stamp-file'
 import { lane_child_invocation } from '#scripts/lane/lane-child-invocation'
+import { run_hold, type RunHold } from '#scripts/run/hold/run-hold'
 import { z } from 'zod'
 import { run_cut_handoff, type Handoff } from './run-cut-handoff'
-import { run_hold, type RunHold } from './run-hold'
 
 // joshuafolkken/kit#1839: a lane child is a detached `fullrun #<N>` process, and the thinking it
 // accumulates while implementing rides on every later API call in the same session — measured at 176K

package/scripts/run/{run-entry-cli.ts → entry/run-entry-cli.ts}

@@ -2,19 +2,19 @@
 import { fileURLToPath } from 'node:url'
 import { josh_command } from '#scripts/josh/josh-run'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
-import { run_cut_report } from './run-cut-report'
+import { run_cut_report } from '#scripts/run/cut/run-cut-report'
+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'
+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_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'
-import { run_halfrun_resume } from './run-halfrun-resume'
-import { run_hold_cli } from './run-hold-cli'
-import { run_label } from './run-label'
-import { run_next } from './run-next'
-import { run_prep } from './run-prep'
-import { run_prep_cli } from './run-prep-cli'
-import { run_prrun_resume } from './run-prrun-resume'
-import { run_stage, type StageCommand, type StageDecision } from './run-stage'
-import { run_stage_read, type StageRead } from './run-stage-read'
-import { run_step } from './run-step'
 
 // `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

package/scripts/run/{run-entry.ts → entry/run-entry.ts}

@@ -1,5 +1,5 @@
-import { run_hold_cli } from './run-hold-cli'
-import { run_step } from './run-step'
+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

package/scripts/run/{run-event-scope.ts → event/run-event-scope.ts}

@@ -1,4 +1,4 @@
-import type { CarryRead } from './run-carry'
+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).

package/scripts/run/{run-event-stream-emit.ts → event/run-event-stream-emit.ts}

@@ -1,5 +1,5 @@
 import { error_text } from '#scripts/lib/error-message'
-import { run_carry } from './run-carry'
+import { run_carry } from '#scripts/run/carry/run-carry'
 import { run_event_scope } from './run-event-scope'
 import { run_event_stream, type RunEvent } from './run-event-stream'
 

package/scripts/run/{run-event-stream.ts → event/run-event-stream.ts}

@@ -168,6 +168,20 @@ function last_position(events: ReadonlyArray<RunEvent>): number {
 
 // The bounded stream serialized back to JSONL. The newest `EVENT_CAP` are kept and the oldest roll off;
 // each survivor keeps its original `pos`, so the bound never renumbers a position a reader is holding.
+// The stream held to `EVENT_CAP`, dropping the oldest trace events before any position
+// (joshuafolkken/kit#3245). A long run's ship-stage and heartbeat lines once filled 396 of the 500 slots
+// and pushed its cuts off, so the retrospective counted `cut 0` for a run with thirteen; a trace says only
+// that the run was alive, so it is the first to go. Only a stream of positions alone rolls them off.
+function bounded(events: ReadonlyArray<RunEvent>): ReadonlyArray<RunEvent> {
+	const excess = events.length - EVENT_CAP
+
+	if (excess <= 0) return events
+
+	const dropped = new Set(events.filter((event) => TRACE_KINDS.has(event.kind)).slice(0, excess))
+
+	return events.filter((event) => !dropped.has(event)).slice(-EVENT_CAP)
+}
+
 function serialize(events: ReadonlyArray<RunEvent>): string {
 	return `${events.map((event) => JSON.stringify(event)).join(LINE_SEPARATOR)}${LINE_SEPARATOR}`
 }
@@ -184,9 +198,9 @@ function append(target: string, kind: string, text: string, at: string): AppendR
 
 	const existing = read_events(target)
 	const position = last_position(existing) + POSITION_INCREMENT
-	const bounded = [...existing, { pos: position, at, kind, text }].slice(-EVENT_CAP)
+	const events = bounded([...existing, { pos: position, at, kind, text }])
 
-	stamp_file.write_text_stamp(target, serialize(bounded))
+	stamp_file.write_text_stamp(target, serialize(events))
 
 	return { appended: true, position }
 }

package/scripts/run/{run-hold-cli.ts → hold/run-hold-cli.ts}

@@ -1,11 +1,11 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
-import { run_halfrun_resume } from './run-halfrun-resume'
+import { run_halfrun_resume } from '#scripts/run/run-halfrun-resume'
+import { run_label } from '#scripts/run/run-label'
+import { run_preflight, type PreflightDecision } from '#scripts/run/run-preflight'
+import { run_prrun_resume } from '#scripts/run/run-prrun-resume'
+import { run_tidy_cli } from '#scripts/run/tidy/run-tidy-cli'
 import { run_hold, type HoldRead, type RunHold } from './run-hold'
-import { run_label } from './run-label'
-import { run_preflight, type PreflightDecision } from './run-preflight'
-import { run_prrun_resume } from './run-prrun-resume'
-import { run_tidy_cli } from './run-tidy-cli'
 
 // `josh run:hold [<N>]` and `josh run:release [<N> | --force]` — the working-tree guard the typed
 // entry points ask before they start (joshuafolkken/kit#1091).

package/scripts/run/{run-merge-cli.ts → merge/run-merge-cli.ts}

@@ -5,12 +5,13 @@ import { CONTEXT_CUT_THRESHOLD } from '#scripts/cost-runtime/context-cut-thresho
 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 { lane_ledger } from '#scripts/lane/lane-ledger'
 import { cli_flags } from '#scripts/lib/cli-flags'
-import { run_carry, type CarryOwner, type RunCarry } from './run-carry'
-import { run_ending } from './run-ending'
-import { run_event_stream } from './run-event-stream'
-import { run_event_stream_emit } from './run-event-stream-emit'
-import { run_issue_number } from './run-issue-number'
+import { run_carry, type CarryOwner, type RunCarry } from '#scripts/run/carry/run-carry'
+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 { run_ending } from '#scripts/run/run-ending'
+import { run_issue_number } from '#scripts/run/run-issue-number'
 import { run_merge, type ChildOutcome, type EndingSignals } from './run-merge'
 import { run_merge_steps, type MergeContext } from './run-merge-steps'
 
@@ -234,6 +235,7 @@ async function on_merged(ctx: MergeContext): Promise<MergeVerdict> {
 	if (refused !== undefined) return report_count_refused(refused)
 
 	await run_event_stream_emit.emit(run_event_stream.EVENT_KIND.MERGE, `#${ctx.child} merged`)
+	await lane_ledger.record_merge(Number(ctx.child))
 
 	if (await run_merge_steps.is_over_budget(ctx.over)) return emit(OVER_TOKEN, SUCCESS_EXIT_CODE)
 
@@ -316,7 +318,10 @@ async function on_parked(ctx: MergeContext): Promise<MergeVerdict> {
 	return emit(await run_merge_steps.ask_next(ctx), SUCCESS_EXIT_CODE)
 }
 
+// A split child: nothing is counted, and its lane is closed when it holds nothing, so the promoted
+// epic does not keep a seat the next child needs (joshuafolkken/kit#3334).
 async function on_skipped(ctx: MergeContext): Promise<MergeVerdict> {
+	await run_merge_steps.close_split_lane(ctx.child)
 	await run_event_stream_emit.emit(run_event_stream.EVENT_KIND.SPLIT, `#${ctx.child} split`)
 
 	return emit(await run_merge_steps.ask_next(ctx), SUCCESS_EXIT_CODE)

package/scripts/run/{run-merge-steps.ts → merge/run-merge-steps.ts}

@@ -9,9 +9,16 @@ import { lane_close } from '#scripts/lane/lane-close'
 import { lane_reap } from '#scripts/lane/lane-reap'
 import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
 import { lane_relaunch } from '#scripts/lane/lane-relaunch'
-import { run_carry, type CarryChange, type CarryOwner, type RunCarry } from './run-carry'
-import { run_carry_conversation } from './run-carry-conversation'
-import { run_cut, type RunCut } from './run-cut'
+import { lane_vacant } from '#scripts/lane/lane-vacant'
+import { poll } from '#scripts/lib/poll'
+import {
+	run_carry,
+	type CarryChange,
+	type CarryOwner,
+	type RunCarry,
+} from '#scripts/run/carry/run-carry'
+import { run_carry_conversation } from '#scripts/run/carry/run-carry-conversation'
+import { run_cut, type RunCut } from '#scripts/run/cut/run-cut'
 import { run_merge } from './run-merge'
 
 // The result of attempting to apply a carry change. Distinguishing `refused` from `applied` lets
@@ -38,6 +45,7 @@ const LANE_CLOSE_OCCASION = 'lane close'
 const GIT_ENTRY = '.git'
 const MERGE_CLOSER = 'pnpm josh run:merge'
 const SINGLE_READ = { attempts: 1, interval_ms: 0 }
+const SYNC_RETRY = { attempts: 3, interval_ms: 5000 }
 // What the driver judged when it parks a child, stated on the issue (joshuafolkken/kit#2769).
 const FAILED_CAUSE = 'the child’s session ended with its issue still open and unfinished.'
 const CUT_RELAUNCH_CAUSE =
@@ -125,10 +133,27 @@ async function refused_carry(ctx: MergeContext): Promise<RunCarry | undefined> {
 	return record.carry
 }
 
+// **A failed `main:sync` is retried before it ends the run** (joshuafolkken/kit#3323): one failure
+// right after a merge — measured while several lanes merged at once — stopped the whole drive, and a
+// hand-run `main:sync` minutes later succeeded. **The error carries the step's stderr, not its
+// stdout**: `main:sync` reports git's refusal on stderr, while stdout carries the wrapper's guard
+// statistics, which is all the old message showed.
 async function sync_main(): Promise<void> {
-	const result = await josh(['main:sync'])
+	// `poll_until` answers only whether it succeeded, so the last attempt's stderr is kept here.
+	let error_output = ''
 
-	if (result.code !== 0) throw new Error(`main:sync failed: ${result.out}`)
+	const is_synced = await poll.poll_until(
+		async () => {
+			const result = await josh(['main:sync'])
+
+			error_output = result.err ?? ''
+
+			return result.code === 0
+		},
+		{ ...SYNC_RETRY, sleeper: poll.sleep },
+	)
+
+	if (!is_synced) throw new Error(`main:sync failed: ${error_output}`)
 }
 
 async function close_lane(child: string): Promise<void> {
@@ -172,6 +197,28 @@ async function preserve_uncommitted(child: string): Promise<boolean> {
 	}
 }
 
+function kept_lane_comment(directory: string): string {
+	return `The split left this issue's lane open: it still holds a commit, an uncommitted change or a live process — ${directory}`
+}
+
+// A child promoted to an epic by a split leaves its lane holding a seat (joshuafolkken/kit#3334): the
+// epic root is never dispatched again, so nothing else would ever close it. The lane is closed only
+// when it holds nothing — no commit, no change, no live process (`lane_vacant`); any other lane is
+// kept, and why is stated on the issue.
+async function close_split_lane(child: string): Promise<void> {
+	const lane = await lane_registry.find_open_lane(child)
+
+	if (lane === undefined) return
+
+	if (await lane_vacant.is_vacant(lane)) {
+		await close_lane(child)
+
+		return
+	}
+
+	await git_gh_issue_write.issue_try_comment(child, kept_lane_comment(lane.directory))
+}
+
 // The progress comment is a human-readable mirror of the carry record, so it is best-effort and only
 // where a named epic has a body to carry it — a pure backlog run keeps the record alone.
 async function post_counters(ctx: MergeContext, carry: RunCarry | undefined): Promise<void> {
@@ -356,6 +403,7 @@ async function ask_next(ctx: MergeContext): Promise<string> {
 const run_merge_steps = {
 	CUT_RELAUNCH_CAUSE,
 	ask_next,
+	close_split_lane,
 	do_failed,
 	do_merged,
 	do_outage,

package/scripts/run/{run-merge.ts → merge/run-merge.ts}

@@ -5,7 +5,7 @@ import {
 	NEEDS_DECISION_LABEL,
 } from '#scripts/issue/issue-labels'
 import type { IssueState } from '#scripts/issue/issue-state'
-import type { CarryChange, RunCarry } from './run-carry'
+import type { CarryChange, RunCarry } from '#scripts/run/carry/run-carry'
 
 // joshuafolkken/kit#2024: a `backlogrun` merge event was two parent turns — a reading turn and an
 // acting turn — spent at the session whose context is largest and whose per-turn cost is highest.

package/scripts/run/{run-progress-cli.ts → progress/run-progress-cli.ts}

@@ -6,7 +6,7 @@ import { backlog_ready } from '#scripts/backlog/backlog-ready'
 import { gh_spawn } from '#scripts/gh/gh-spawn'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
 import { error_text } from '#scripts/lib/error-message'
-import { run_event_stream_emit } from './run-event-stream-emit'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
 import { run_progress, type ProgressState } from './run-progress'
 import { run_progress_args, type ParsedValues } from './run-progress-args'
 import { run_progress_clock } from './run-progress-clock'