@joshuafolkken/kit 1.1784.0 → 1.2116.0

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

@@ -5,13 +5,14 @@ import { issue_watch } from '#scripts/issue/issue-watch'
 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 { lane_plan_check } from '#scripts/lane/lane-plan-check'
 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'
 import { run_next } from '#scripts/run/run-next'
-import { run_prep } from '#scripts/run/run-prep'
+import type { PrepParts } 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 {
@@ -24,7 +25,9 @@ import { run_stage_read, type StageRead } from '#scripts/run/run-stage-read'
 import { run_step } from '#scripts/run/run-step'
 import { run_step_section } from '#scripts/run/run-step-section'
 import { run_entry, type EntryParts } from './run-entry'
+import { run_entry_spill } from './run-entry-spill'
 import { run_entry_stop } from './run-entry-stop'
+import { run_entry_trust, type TrustStop } from './run-entry-trust'
 
 // `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
@@ -50,6 +53,8 @@ const NEWLINE = '\n'
 const HOLD_STOP_NOTE =
 	'(tree not held — see the reason above; clean up and retry, or release with `pnpm josh run:release`)'
 const COST_STOP_NOTE = '(session budget spent — see the figure above; resume in a fresh session)'
+const YIELD_NOTE =
+	'(lane given back at the entry — see the overlap above; end the session now, with no edit)'
 const { BUDGET_REASON, HOLD_REASON } = run_entry_stop
 const HALFRUN_RESUME_TOKEN = 'halfrun'
 
@@ -123,8 +128,9 @@ async function check_cost(): Promise<string> {
 }
 
 interface Reads {
-	report: string
+	prep: PrepParts
 	verdict: string
+	trust_stop: TrustStop | undefined
 }
 
 // The issue reads and the pre-implementation verdict, from the one gather `run:prep` and `run:next`
@@ -132,20 +138,33 @@ interface Reads {
 // 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)
-	const parts = run_prep_cli.to_parts(issue_number, reads)
-	const verdict = run_step.pre_verdict(run_next.to_input(parts))
+	const prep = run_prep_cli.to_parts(issue_number, reads)
+	const verdict = run_step.pre_verdict(run_next.to_input(prep))
+	const trust_stop = run_entry_trust.stop_of(reads.content, reads.state, issue_number)
 
-	return { report: run_prep.format_report(parts), verdict }
+	return { prep, verdict, trust_stop }
+}
+
+function entry_text(parts: EntryParts): string {
+	return session_cite.text(run_entry.format_report(parts))
 }
 
 function emit(parts: EntryParts): number {
-	console.info(session_cite.text(run_entry.format_report(parts)))
+	console.info(entry_text(parts))
 
 	return run_entry.exit_code(parts)
 }
 
-// The summary of a run that stopped before it read the issue: the token that stopped it, no verdict,
-// and the note that stands in for the report body.
+// The bundle emitted as it fits the Bash result, measured on the composite `emit` prints.
+function emit_fitted(entry: Omit<EntryParts, 'report'>, prep: PrepParts): number {
+	const report = run_entry_spill.fit(prep, (text) => entry_text({ ...entry, report: text }))
+
+	return emit({ ...entry, report })
+}
+
+// The summary of a run that stopped without a report — before it read the issue, or after reading an
+// issue it will not run: the token that stopped it, no verdict, and the note that stands in for the
+// report body.
 function stop_report(issue_number: string, hold: string, cost: string, report: string): number {
 	return emit({ issue_number, hold, cost, verdict: run_entry.NO_VERDICT, report })
 }
@@ -157,16 +176,37 @@ interface StopCall {
 	command: StageCommand
 	reason: string
 	should_release: boolean
+	recommended?: string
 }
 
-async function stop_run({ parts, command, reason, should_release }: StopCall): Promise<number> {
+async function stop_run({ parts, command, ...notice }: StopCall): Promise<number> {
 	const code = stop_report(parts.issue_number, parts.hold, parts.cost, parts.report)
 
-	await run_entry_stop.stop({ issue_number: parts.issue_number, command, reason, should_release })
+	await run_entry_stop.stop({ issue_number: parts.issue_number, command, ...notice })
 
 	return code
 }
 
+// **An untrusted author's issue stops after the reads, not before the claim** — the trust is decided
+// by the read `run:prep` already makes, so the gate adds no call; the hold this call claimed is
+// released. It exits non-zero though the hold and the budget both allowed the run. A trust read that
+// failed stops here too, under its own reason (`run-entry-trust.ts`).
+async function stop_untrusted(
+	{ issue_number, command }: EntryRequest,
+	{ hold, cost }: Pick<EntryParts, 'hold' | 'cost'>,
+	{ reason, report, recommended }: TrustStop,
+): Promise<number> {
+	await stop_run({
+		parts: { issue_number, hold, cost, report },
+		command,
+		reason,
+		should_release: true,
+		recommended,
+	})
+
+	return FAILURE_EXIT_CODE
+}
+
 interface Resume {
 	token: string
 	code: number
@@ -250,17 +290,50 @@ async function mark_planned(issue_number: string, state: StageState): Promise<vo
 	if (state === run_stage.PLANNED) await run_event_plan.emit_plan(issue_number)
 }
 
+// **A lane child probes its declared paths before the investigation** (joshuafolkken/kit#5211): a running
+// lane that planned one of them since dispatch takes the lane back here, at the cost of the entry
+// alone, rather than after the investigation `lane:plan` would otherwise yield on. `lane:plan` has
+// already released the hold and noted the yield, so this only reports it — no stop notice, as for
+// any yield.
+async function yields_at_entry(issue_number: string): Promise<boolean> {
+	if (!lane_child_marker.is_child_of(process.cwd())) return false
+
+	return await lane_plan_check.yield_at_entry(Number(issue_number))
+}
+
+// The report of a lane given back at the entry, exiting as `lane:plan` does on a yield.
+function yield_report(
+	issue_number: string,
+	{ hold, cost }: Pick<EntryParts, 'hold' | 'cost'>,
+): number {
+	stop_report(issue_number, hold, cost, YIELD_NOTE)
+
+	return lane_plan_check.YIELD_EXIT_CODE
+}
+
 // The tree is held and the budget allows the run, so the issue is marked as running before its reads
 // — the label then shows in the `labels:` line the report below carries.
-async function proceed(issue_number: string, hold: string, cost: string): Promise<number> {
+// The plan event is written only once the run passed the trust gate.
+async function proceed(
+	request: EntryRequest,
+	{ hold, cost }: Pick<EntryParts, 'hold' | 'cost'>,
+	state: StageState,
+): Promise<number> {
+	const { issue_number } = request
+
 	await run_label.mark(issue_number)
 	const reads = await gather_reads(issue_number)
 
+	if (reads.trust_stop) return await stop_untrusted(request, { hold, cost }, reads.trust_stop)
+	if (await yields_at_entry(issue_number)) return yield_report(issue_number, { hold, cost })
+
+	await mark_planned(issue_number, state)
+
 	// The issue the report prints is the one the run has read, so it is the baseline a person's later
 	// update is measured against (`issue-watch.ts`).
 	await issue_watch.record_baseline_here(issue_number)
 
-	const code = emit({ issue_number, hold, cost, verdict: reads.verdict, report: reads.report })
+	const code = emit_fitted({ issue_number, hold, cost, verdict: reads.verdict }, reads.prep)
 
 	// The entry's own read — the split assessment every run answers before its work — printed here so
 	// the reader does not spend a turn fetching it.
@@ -269,10 +342,8 @@ async function proceed(issue_number: string, hold: string, cost: string): Promis
 	return run_step_section.print_section(run_step_section.ENTRY)
 }
 
-async function claim_run(
-	{ issue_number, command }: EntryRequest,
-	state: StageState,
-): Promise<number> {
+async function claim_run(request: EntryRequest, state: StageState): Promise<number> {
+	const { issue_number, command } = request
 	const hold = await claim_hold(issue_number, command)
 
 	if (hold !== run_hold_cli.HOLD_VERDICT) {
@@ -289,9 +360,7 @@ async function claim_run(
 		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)
+	return await proceed(request, { hold, cost }, state)
 }
 
 // A carried cut is asked first, before anything is read (`run:cut --resume`); `kickoff` claims and cuts

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

@@ -0,0 +1,83 @@
+import { mkdtempSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { capped_output } from '#scripts/document/capped-print'
+import { capped_print_part } from '#scripts/document/capped-print-part'
+import { document_section } from '#scripts/document/document-section'
+import { document_section_cli } from '#scripts/document/document-section-cli'
+import { PLATFORM_TEMP_ROOT } from '#scripts/josh/platform-temporary'
+import { run_prep, type PrepParts } from '#scripts/run/run-prep'
+import { run_step_section } from '#scripts/run/run-step-section'
+
+// The `run:prep` bundle `run:entry` prints, kept under the Bash result cap (joshuafolkken/kit#5213).
+// Past the cap the harness hands back a preview, and a lane child re-ran `run:entry` into a file to see
+// the rest — two calls and two copies of the bundle in the context the implementation cut is measured on.
+//
+// **Over the budget, the whole bundle goes to one file and the issue section becomes its path.** The
+// stage, the `entry` line, the `prep` summary and the short sections stay inline, so the run still
+// branches on what it printed; the issue body and comments — the one unbounded section — are read from
+// the file. A bundle still over the budget without them keeps only the summary and the path.
+//
+// **The file has `capped_print`'s shape** — a fresh directory per call holding one part — so the
+// investigation guard already reads it as a session artifact, not as the Issue's subject.
+//
+// **The budget is `capped_output`'s, less what shares the same Bash result**: the split assessment's
+// section `run:entry` prints after the bundle, and a second headroom for the stage line and the
+// stderr the hold forwards before it.
+
+const FILE_MODE = 0o600
+const SECTION_SEPARATOR = '\n\n'
+
+function byte_length(text: string): number {
+	return Buffer.byteLength(text, 'utf8')
+}
+
+function entry_section_length(root: string): number {
+	const found = run_step_section.GOVERNING_SECTIONS.get(run_step_section.ENTRY)
+
+	if (found === undefined) return 0
+
+	const file = document_section_cli.resolve_document(found.document, root)
+	const markdown = document_section.read_optional(file) ?? ''
+
+	return byte_length(document_section.section(markdown, found.heading)?.text ?? '')
+}
+
+function report_budget(root: string): number {
+	const shared = entry_section_length(root) + capped_output.HEADROOM_CHARS
+
+	return capped_output.output_budget(root) - shared
+}
+
+function spill(whole: string): string {
+	const directory = mkdtempSync(path.join(PLATFORM_TEMP_ROOT, capped_print_part.DIRECTORY_PREFIX))
+	const file = path.join(directory, capped_print_part.part_name(0))
+	const size = byte_length(whole).toLocaleString('en-US')
+
+	writeFileSync(file, whole, { flag: 'wx', mode: FILE_MODE })
+
+	return `Over the Bash cap — the whole bundle (${size} B, the issue body and comments included) is written to ${file}; read it with the Read tool, once, not cat.`
+}
+
+// `compose` turns a report into the text `run:entry` prints for it, so the measure is of what reaches
+// the Bash result — the `entry` line and the cited links included — not of the report alone.
+function fit(
+	parts: PrepParts,
+	compose: (report: string) => string,
+	root: string = process.cwd(),
+): string {
+	const budget = report_budget(root)
+	const whole = run_prep.format_report(parts)
+
+	if (byte_length(compose(whole)) <= budget) return whole
+
+	const line = spill(whole)
+	const trimmed = run_prep.format_report({ ...parts, content_body: line })
+
+	if (byte_length(compose(trimmed)) <= budget) return trimmed
+
+	return [run_prep.summary(parts), line].join(SECTION_SEPARATOR)
+}
+
+const run_entry_spill = { fit, report_budget }
+
+export { run_entry_spill }

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

@@ -23,6 +23,8 @@ interface StopNotice {
 	command: string
 	reason: string
 	should_release: boolean
+	// The choice the Telegram recommends where a rerun alone would stop the same way again.
+	recommended?: string
 }
 
 interface StopPorts {
@@ -79,7 +81,9 @@ async function notify_stop(notice: StopNotice, ports: StopPorts): Promise<void>
 		issue_title: `${notice.command} ${issue_cite.plain(notice.issue_number)} stopped`,
 		body: body_of(notice),
 		recovery: RECOVERY,
-		recommended: `Run \`${notice.command} ${issue_cite.plain(notice.issue_number)}\` again in a fresh session`,
+		recommended:
+			notice.recommended ??
+			`Run \`${notice.command} ${issue_cite.plain(notice.issue_number)}\` again in a fresh session`,
 		alternatives: [LATER_ALTERNATIVE],
 	})
 

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

@@ -0,0 +1,91 @@
+import { issue_cite } from '#scripts/issue/issue-cite'
+import type { BlockRead, BlockTrust } from '#scripts/issue/issue-read-cli'
+import { issue_state } from '#scripts/issue/issue-state'
+import type { StateRead } from '#scripts/issue/issue-state-cli'
+
+// **An issue filed by an author without write access is not run on its own body**
+// (joshuafolkken/kit#4663). `backlogrun` never offers one, but a person can still name it as
+// `fullrun #N`, and its body would then reach the run as the specification. The run goes ahead only
+// once a trusted person has planned it with `kickoff #N` — the `run:planned` label and a comment from
+// an author with write access, the plan the run then follows instead of the body. Both, because the
+// label alone is within triage access and a trusted comment alone may be an automated one.
+//
+// Decided from the reads `run:prep` already made, so the gate costs no further call. A read that
+// failed is not judged here: `run:entry` already exits non-zero on it.
+//
+// **A trust read that failed stops as the failed read it is** (#4703) — a write-access lookup, the
+// comment listing or the label read that answered nothing still stops the run, but naming an
+// untrusted author there sends a person to plan an issue whose author may well be trusted.
+
+const STOP_REASON =
+	'the issue author does not have write access, and no trusted `kickoff` plan is on the issue'
+const UNREAD_REASON =
+	'the write-access lookup, the comment listing or the label read failed, so whether the issue may run on its body could not be read'
+const UNREAD_REMEDY = 'Check `gh auth status` and the network, then run it again'
+
+// What a stopped run prints, notifies and recommends.
+interface TrustStop {
+	reason: string
+	report: string
+	recommended: string
+}
+
+// The remedy, named with the issue: a trusted person's `kickoff` writes the plan the run will follow.
+function recommended(issue_number: string): string {
+	return `Have a person with write access run \`kickoff ${issue_cite.plain(issue_number)}\`, then run it again`
+}
+
+function untrusted_stop(issue_number: string): TrustStop {
+	const remedy = recommended(issue_number)
+
+	return {
+		reason: STOP_REASON,
+		report: `(issue author not trusted — ${remedy})`,
+		recommended: remedy,
+	}
+}
+
+const UNREAD_STOP: TrustStop = {
+	reason: UNREAD_REASON,
+	report: `(issue trust read failed — ${UNREAD_REMEDY})`,
+	recommended: UNREAD_REMEDY,
+}
+
+// Not cleared, and the read that would have cleared it answered nothing — a label read that failed
+// leaves the plan unknown unless the comment listing already ruled it out.
+function is_unread(trust: BlockTrust, state: StateRead): boolean {
+	const { is_body_trusted, has_trusted_comment } = trust
+
+	if (is_body_trusted === undefined) return true
+
+	const can_be_planned = state.kind !== 'state' || issue_state.is_planned(state)
+
+	return can_be_planned && has_trusted_comment !== false
+}
+
+// The plan is asked only of a body not already trusted — the state read is not needed otherwise.
+function untrusted_body_stop(
+	trust: BlockTrust,
+	state: StateRead,
+	issue_number: string,
+): TrustStop | undefined {
+	if (issue_state.is_planned(state) && trust.has_trusted_comment === true) return undefined
+
+	return is_unread(trust, state) ? UNREAD_STOP : untrusted_stop(issue_number)
+}
+
+// The stop an issue's trust calls for, or `undefined` when the run may go ahead.
+function stop_of(
+	content: BlockRead,
+	state: StateRead,
+	issue_number: string,
+): TrustStop | undefined {
+	if (content.kind !== 'ok' || content.trust.is_body_trusted === true) return undefined
+
+	return untrusted_body_stop(content.trust, state, issue_number)
+}
+
+const run_entry_trust = { STOP_REASON, UNREAD_REASON, stop_of }
+
+export type { TrustStop }
+export { run_entry_trust }

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

@@ -0,0 +1,56 @@
+// The wording of the baseline investigation's notes on the run's event stream (joshuafolkken/kit#4887):
+// `lane-baseline.ts` writes the launch and a failure, the session it launches writes its result, and
+// `lane-baseline.ts` reads them back so a merge count is investigated once. `run:board` shows each as a
+// note, since none reads as an overrun note.
+
+const MERGES_PATTERN = /^baseline @(?<merges>\d+) merges: (?<rest>.*)$/u
+const STARTED_PREFIX = 'started — '
+const FAILED_PREFIX = 'baseline investigation failed: '
+
+type BaselineNote =
+	| { kind: 'started'; merges: number; outcome: string }
+	| { kind: 'ended'; merges: number; result: string }
+	| { kind: 'failed'; note: string }
+
+function merges_text(merges: number, rest: string): string {
+	return `baseline @${String(merges)} merges: ${rest}`
+}
+
+// The launch at the `merges`-th merge, and what became of it.
+function started_text(merges: number, outcome: string): string {
+	return merges_text(merges, `${STARTED_PREFIX}${outcome}`)
+}
+
+// The session's result — the overrun investigation's vocabulary (`lane-overrun-prompt.ts`).
+function ended_text(merges: number, result: string): string {
+	return merges_text(merges, result)
+}
+
+// A failure — reading the ledger, or the launch itself — names no merge count, so a later merge asks
+// again.
+function failed_text(note: string): string {
+	return `${FAILED_PREFIX}${note}`
+}
+
+function merges_note(merges: number, rest: string): BaselineNote {
+	if (rest.startsWith(STARTED_PREFIX)) {
+		return { kind: 'started', merges, outcome: rest.slice(STARTED_PREFIX.length) }
+	}
+
+	return { kind: 'ended', merges, result: rest }
+}
+
+function parse(text: string): BaselineNote | undefined {
+	const note = text.slice(FAILED_PREFIX.length)
+
+	if (text.startsWith(FAILED_PREFIX)) return { kind: 'failed', note }
+
+	const groups = MERGES_PATTERN.exec(text)?.groups
+
+	return groups ? merges_note(Number(groups['merges']), groups['rest'] ?? '') : undefined
+}
+
+const run_event_baseline = { ended_text, failed_text, parse, started_text }
+
+export type { BaselineNote }
+export { run_event_baseline }

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

@@ -29,14 +29,18 @@ interface Filed {
 	// outside the run sharing the repository's stream (joshuafolkken/kit#4099). An event written before
 	// the mark was recorded reads as filed outside.
 	is_run?: boolean | undefined
+	// A lane's overrun investigation filed it, not the child (joshuafolkken/kit#4880). An event written
+	// before the mark was recorded reads as the child's.
+	is_overrun?: boolean | 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. The run's mark follows the kind slot, again with no space.
+// kind. The run's mark follows the kind slot, then the overrun's, again with no space.
 const RUN_MARK = '[run]'
+const OVERRUN_MARK = '[overrun]'
 const TEXT_PATTERN = new RegExp(
-	String.raw`^(?<reference>\S*#\d+)(?:\[(?<kind>${KINDS.join('|')}|)\](?<run>\[run\])?)? (?<title>.*?)(?: \(found during #(?<during>\d+)\))?$`,
+	String.raw`^(?<reference>\S*#\d+)(?:\[(?<kind>${KINDS.join('|')}|)\](?<run>\[run\])?(?<overrun>\[overrun\])?)? (?<title>.*?)(?: \(found during #(?<during>\d+)\))?$`,
 	'u',
 )
 
@@ -46,7 +50,8 @@ function kind_of(labels: ReadonlyArray<string>): FiledKind | undefined {
 }
 
 function text_of(filed: Filed): string {
-	const kind = `[${filed.kind ?? ''}]${filed.is_run === true ? RUN_MARK : ''}`
+	const marks = `${filed.is_run === true ? RUN_MARK : ''}${filed.is_overrun === true ? OVERRUN_MARK : ''}`
+	const kind = `[${filed.kind ?? ''}]${marks}`
 	const suffix =
 		filed.found_during === undefined
 			? ''
@@ -66,6 +71,7 @@ function parse(text: string): Filed | undefined {
 		title: String(groups['title']),
 		found_during: groups['during'],
 		is_run: groups['run'] !== undefined,
+		is_overrun: groups['overrun'] !== undefined,
 	}
 }