@joshuafolkken/kit 1.1784.0 → 1.2114.0

package/scripts/run/review/run-review.ts

@@ -1,7 +1,7 @@
 // The pure decisions `josh run:review` makes, kept apart from the side effects the same way
 // `run-merge.ts` is kept apart from `run-merge-steps.ts`.
 //
-// `run:review` starts the gate in the background and prints the `/code-review` brief in one call, so a
+// `run:review` starts the gate in the background and writes the `/code-review` brief in one call, so a
 // lane child launches both from a single command and the two overlap rather than running one after the
 // other. Two facts have to be decided from what the stamps say, and both are decided here so a test can
 // pin them without a gate ever running:
@@ -29,21 +29,37 @@ function adopt_verdict(is_gate_green: boolean): AdoptVerdict {
 const GATE_GREEN = 'green'
 const GATE_RUNNING = 'running'
 const GATE_RED = 'red'
+const GATE_MOVED = 'moved'
 
-type GateState = typeof GATE_GREEN | typeof GATE_RUNNING | typeof GATE_RED
+type GateState = typeof GATE_GREEN | typeof GATE_RUNNING | typeof GATE_RED | typeof GATE_MOVED
 
-// The three states the join waits on, decided from two readings the steps take of the stamps a real
-// `josh gate` writes: a green stamp covering this tree, and the in-flight marker's writer still alive.
+// The four states the join waits on, decided from three readings the steps take of the stamps a real
+// `josh gate` writes: a green stamp covering this tree, the in-flight marker's writer still alive, and
+// a green stamp covering the tree this pair's gate started on.
 // Green wins over running, because a gate that has already recorded green is done however the marker
 // reads; a marker whose writer is gone with no green stamp is a gate that finished red or died, which
 // is the safe direction — the join reports red and the verdict is blocked.
-function gate_state(is_green: boolean, is_running: boolean): GateState {
+//
+// **A gate that finished green on a tree that has since moved is not red** (joshuafolkken/kit#4774): a
+// round-1 reviewer fixing in place moves the tree after the gate recorded green, so the stamp no longer
+// covers it. That is `moved` — still not adoptable, but the gate never failed, and the gate that
+// follows re-runs on the moved tree.
+function gate_state(is_green: boolean, is_running: boolean, is_moved = false): GateState {
 	if (is_green) return GATE_GREEN
 	if (is_running) return GATE_RUNNING
+	if (is_moved) return GATE_MOVED
 
 	return GATE_RED
 }
 
+// The `--join` exit code of a `moved` gate, read by `josh ship` (`run-ship-review-steps.ts`).
+const MOVED_EXIT_CODE = 2
+// The `--join` exit code of an unpinned change the background `test:pinned` found
+// (joshuafolkken/kit#4770). `josh ship` never drains it, whatever the reviewer fixed.
+const UNPINNED_EXIT_CODE = 3
+// `josh ship` opens the interaction brief itself, so its `run:review` opens code's alone.
+const CODE_ONLY_FLAG = '--code-only'
+
 function is_gate_settled(state: GateState): boolean {
 	return state !== GATE_RUNNING
 }
@@ -100,9 +116,13 @@ function format_timing(timing: ReviewTiming): string {
 const run_review = {
 	ADOPT,
 	BLOCKED,
+	CODE_ONLY_FLAG,
 	GATE_GREEN,
+	GATE_MOVED,
 	GATE_RED,
 	GATE_RUNNING,
+	MOVED_EXIT_CODE,
+	UNPINNED_EXIT_CODE,
 	adopt_verdict,
 	format_timing,
 	gate_state,
@@ -115,4 +135,4 @@ export type { AdoptVerdict, GateState, ReviewTiming, TimingStart }
 // object their literal types widen to `string`, so a test passing `run_review.GATE_RED` to a
 // `GateState` parameter would not type-check — the same reason `run-liveness.ts` exports its verdicts
 // by name.
-export { GATE_GREEN, GATE_RED, GATE_RUNNING, run_review }
+export { GATE_GREEN, GATE_MOVED, GATE_RED, GATE_RUNNING, run_review }

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

@@ -1,9 +1,7 @@
-import { CONTEXT_CUT_THRESHOLD } from '#scripts/cost-runtime/context-cut-threshold'
 import { cost_cli, type CostVerdict } from '#scripts/cost-runtime/cost-cli'
 import { cost_verdict } from '#scripts/cost-runtime/cost-verdict'
 import { hook_decision } from '#scripts/josh/hook-decision'
 import { error_text } from '#scripts/lib/error-message'
-import { figure_format } from '#scripts/lib/figure-format'
 import { implementation_cut_verdict } from '#scripts/rules/implementation-cut-verdict'
 import type { RunCarry } from '#scripts/run/carry/run-carry'
 import { run_headless } from './run-headless'
@@ -50,10 +48,11 @@ function current_state(): ParentCutState {
 	}
 }
 
-const THRESHOLD_TEXT = `${figure_format.format_tokens(CONTEXT_CUT_THRESHOLD)}-token`
+// Named by its command, never spelled: the threshold is priced at the session's own model.
+const THRESHOLD_TEXT = '`pnpm josh cost --cut`'
 
 const PARENT_CUT_REASON =
-	'⛔ backlogrun parent hand-off: this session drives a `backlogrun` and its recent-context cost ' +
+	'⛔ backlogrun parent hand-off: this session drives a `backlogrun` and its recent context ' +
 	`crossed the ${THRESHOLD_TEXT} threshold between merges. Take the hand-off now: open no new lane, ` +
 	'follow `backlogrun-progress.md` → "The hand-off" (`pnpm josh run:carry --cut --owner "$PPID"`, then ' +
 	'`pnpm josh run:wake` unless `capped`) and end the turn. Reissue this call once done or if it ' +

package/scripts/run/run-prep.ts

@@ -109,6 +109,7 @@ const run_prep = {
 	SUMMARY_PREFIX,
 	format_report,
 	ship_body,
+	summary,
 }
 
 export type { PrepParts }

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

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

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

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

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

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

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

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

package/scripts/run/run-step.ts

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

package/scripts/run/ship/run-ship-args.ts

@@ -21,6 +21,7 @@ const TRAILING_ISSUE_PATTERN = /#([1-9]\d*)\s*$/u
 // shell-body-safe `--notify-message-file` a body naming a command or path must use (`followup.md`).
 const NOTIFY_OPTIONS = ['notify-message', 'notify-message-file'] as const
 const { BODY_FILE_OPTION, body_arguments } = run_ship_body_draft
+const UNPINNED_OK_OPTION = 'unpinned-ok'
 
 type NotifyValues = Partial<Record<(typeof NOTIFY_OPTIONS)[number], string>>
 
@@ -35,6 +36,8 @@ const OPTIONS = {
 	detach: { type: 'boolean' },
 	log: { type: 'string' },
 	cite: { type: 'string', multiple: true },
+	// Forwarded to round 1's `run:review`, the only way past a change no test can pin under `--review`.
+	[UNPINNED_OK_OPTION]: { type: 'string' },
 } as const
 
 type ShipCommand = { kind: 'ship'; args: ShipArguments } | { kind: 'log'; number: string }
@@ -59,6 +62,20 @@ interface ParsedValues extends NotifyValues {
 	detach?: boolean
 	log?: string
 	cite?: Array<string>
+	[UNPINNED_OK_OPTION]?: string
+}
+
+function unpinned_arguments(reason: string | undefined): ReadonlyArray<string> {
+	return reason === undefined ? [] : [`--${UNPINNED_OK_OPTION}`, reason]
+}
+
+// `--unpinned-ok` answers round 1's `run:review` alone, so without `--review` or with a blank reason it
+// would reach nothing that reads it — refused here rather than after the earlier stages have run.
+function is_stray_unpinned_ok(values: ParsedValues): boolean {
+	const reason = values[UNPINNED_OK_OPTION]
+	if (reason === undefined) return false
+
+	return values.review !== true || reason.trim() === ''
 }
 
 // A follow-up citation passed as a trailing positional is a bare issue number, so a stray flag is
@@ -84,6 +101,7 @@ function ship_args(
 		cites,
 		is_review: values.review === true,
 		is_detach: values.detach === true,
+		unpinned_ok: unpinned_arguments(values[UNPINNED_OK_OPTION]),
 	}
 }
 
@@ -99,6 +117,7 @@ function command_of(
 	positionals: ReadonlyArray<string>,
 ): ShipCommand | undefined {
 	if (values.log !== undefined) return log_command(values.log, positionals)
+	if (is_stray_unpinned_ok(values)) return undefined
 
 	const title = positionals[FIRST]
 	const args =

package/scripts/run/ship/run-ship-brokered-review.ts

@@ -0,0 +1,106 @@
+import { stamp_file } from '#scripts/josh/stamp-file'
+import {
+	lane_session_action,
+	type BrokerAnswer,
+	type ReviewRound,
+} from '#scripts/lane/lane-session-action'
+import { lane_session_broker } from '#scripts/lane/lane-session-broker'
+import { review_attest, type ReviewSlot } from '#scripts/review/review-attest'
+
+// A lane child's reviewers started by the lane's broker (`run-ship-reviewer.ts`). `/code-review` alone
+// omits `slots`, so a broker still on the code before them reads the request.
+//
+// **A broker that cannot read `slots` still reviews every slot**: the supervisor reloads on new code
+// only at its next pass boundary (`run-wake-code.ts`), so the ship that first runs both reviews together
+// meets a broker that never learned them (joshuafolkken/kit#4672). Each slot then goes in turn as a
+// `/code-review` request — its brief staged at the code slot's file, its findings moved to its own — and
+// the code slot goes last, with its own brief put back.
+
+const { CODE } = review_attest.REVIEW_SLOT
+
+function copy_stamp(source: string, target: string): void {
+	const text = stamp_file.read_stamp_text(source)
+
+	if (text !== undefined) stamp_file.write_text_stamp(target, text)
+}
+
+async function code_request(
+	directory: string,
+	issue: string,
+	round: ReviewRound,
+): Promise<BrokerAnswer> {
+	return await lane_session_broker.request(directory, issue, { kind: 'review', round })
+}
+
+async function staged_review(
+	directory: string,
+	issue: string,
+	round: ReviewRound,
+	slot: ReviewSlot,
+): Promise<BrokerAnswer> {
+	const code = lane_session_broker.review_paths(directory)
+	const own = lane_session_broker.review_paths(directory, slot)
+
+	copy_stamp(own.brief, code.brief)
+	const answer = await code_request(directory, issue, round)
+
+	copy_stamp(code.findings, own.findings)
+	stamp_file.remove_stamp(code.findings)
+
+	return answer
+}
+
+// One after another, since every slot shares the code slot's files.
+async function staged_reviews(
+	directory: string,
+	issue: string,
+	round: ReviewRound,
+	slots: ReadonlyArray<ReviewSlot>,
+): Promise<ReadonlyArray<BrokerAnswer>> {
+	const [slot, ...rest] = slots
+	if (slot === undefined) return []
+
+	const answer = await staged_review(directory, issue, round, slot)
+
+	return [answer, ...(await staged_reviews(directory, issue, round, rest))]
+}
+
+async function in_turn(
+	directory: string,
+	issue: string,
+	round: ReviewRound,
+	slots: ReadonlyArray<ReviewSlot>,
+): Promise<BrokerAnswer> {
+	const code_brief = lane_session_broker.review_paths(directory).brief
+	const kept = stamp_file.read_stamp_text(code_brief)
+	const others = slots.filter((slot) => slot !== CODE)
+	const answers = [...(await staged_reviews(directory, issue, round, others))]
+
+	if (kept !== undefined) stamp_file.write_text_stamp(code_brief, kept)
+	if (slots.includes(CODE)) answers.push(await code_request(directory, issue, round))
+
+	return answers.find((answer) => !answer.is_success) ?? lane_session_action.SUCCESS
+}
+
+async function request(
+	directory: string,
+	issue: string,
+	round: ReviewRound,
+	slots: ReadonlyArray<ReviewSlot>,
+): Promise<BrokerAnswer> {
+	if (slots.length === 1 && slots[0] === CODE) return await code_request(directory, issue, round)
+
+	const answer = await lane_session_broker.request(directory, issue, {
+		kind: 'review',
+		round,
+		slots,
+	})
+
+	if (!lane_session_broker.is_unreadable(answer)) return answer
+
+	return await in_turn(directory, issue, round, slots)
+}
+
+const run_ship_brokered_review = { request }
+
+export { run_ship_brokered_review }