@joshuafolkken/kit 1.1471.0 → 1.1784.0

package/scripts/run/merge/run-merge.ts

@@ -1,12 +1,13 @@
-import { issue_cite } from '#scripts/issue/issue-cite'
 import {
-	ALREADY_DONE_LABEL,
 	EPIC_LABEL,
 	has_label_name,
-	NEEDS_DECISION_LABEL,
+	has_parked_label,
+	RUN_STALLED_LABEL,
 } from '#scripts/issue/issue-labels'
 import type { IssueState } from '#scripts/issue/issue-state'
 import type { CarryChange, RunCarry } from '#scripts/run/carry/run-carry'
+import { run_stalled } from '#scripts/run/park/run-stalled'
+import type { ChildOutcome } from './run-merge-outcome'
 
 // The pure core of `run:merge`, the one composite command for a `backlogrun` merge event: the parent —
 // the session whose context is largest and per-turn cost highest — calls `run:merge <N>` once at a
@@ -24,10 +25,11 @@ const CLOSED_STATE = 'CLOSED'
 // failing every child it is handed rather than on failures scattered across a long run.
 const CONSECUTIVE_FAILURE_LIMIT = 3
 // Three outages in a row stop the run too — the same shape as the failure
-// guard, over its own streak. An outage is a child its environment ended — it could not reach the API,
-// its session was killed inside a turn, or its ship stopped with no relaunch — so a run of them is
-// the environment being down; stopping is what keeps the run from re-dispatching into a dead API
-// forever. A merge or a genuine child failure resets it (`run-carry.ts` → `next_outages`).
+// guard, over its own streak. An outage is a child its environment ended — it could not reach the API
+// or its session was killed inside a turn — so a run of them is the environment being down; stopping is
+// what keeps the run from re-dispatching into a dead API forever. A ship that stopped with no relaunch
+// is re-dispatched too but not counted: its child reached the API (joshuafolkken/kit#3974). A merge or
+// a genuine child failure resets it (`run-carry.ts` → `next_outages`).
 const CONSECUTIVE_OUTAGE_LIMIT = 3
 const ONE = 1
 
@@ -37,25 +39,22 @@ const ONE = 1
 //                   child a merged pull request's `closes #N` names — GitHub merged it without closing
 //                   the issue.
 // - `human-review` — OPEN and carrying `needs-human-review`; the run's own ending (needs-human-review.md).
-// - `parked`      — OPEN and carrying `needs-decision` or `already-done`; a person still owns it.
+// - `parked`      — OPEN and carrying a park label (`PARKED_LABELS`); a person still owns it.
 // - `split`       — OPEN and carrying `epic`; its work was divided into new children.
-// - `outage`      — OPEN and carrying neither, but the exit record shows it could not reach the API; not
-//                   the child's failure, so it is re-dispatchable and uncounted against the failure guard.
+// - `outage`      — OPEN and carrying neither, but the exit record shows it could not reach the API, a
+//                   host restart killed it, or its ship stop went unanswered; not the child's failure, so
+//                   it is re-dispatchable and uncounted against the failure guard.
 // - `cut`         — OPEN and carrying neither, but its lane holds a declared cut no successor adopted;
 //                   the child ended its session on purpose, so it is resumed rather than parked and
 //                   counts nothing.
+// - `unauthenticated` — OPEN and carrying neither, but the exit record shows the session could not
+//                   authenticate; no child can run until a person runs `/login`, so the run stops with
+//                   the child left `in-progress` and nothing counted (joshuafolkken/kit#4216).
 // - `failed`      — OPEN and carrying neither, and not an outage; the child did not finish.
+// - `withdrawn`   — a person withdrew it with `lane:withdraw`, read from the event stream before the
+//                   GitHub state: left OPEN for the next run, it is neither merged nor failed.
 // - `unresolved`  — the state could not be read; re-read before deciding.
-type ChildOutcome =
-	| 'merged'
-	| 'human-review'
-	| 'parked'
-	| 'split'
-	| 'cut'
-	| 'outage'
-	| 'failed'
-	| 'unresolved'
-	| 'shipping'
+// The names themselves are `run-merge-outcome.ts`'s.
 
 // What the CLI read beside the GitHub state: whether the exit record is an API outage, and whether the
 // lane holds a cut its successor never adopted.
@@ -65,6 +64,13 @@ interface EndingSignals {
 	// The merged pull request whose `closes #N` names the child, when GitHub left the child OPEN after
 	// merging it.
 	merged_pr?: string | undefined
+	// The newest launch of the child was withdrawn by a person (`run_event_scope.is_withdrawn`).
+	is_withdrawn?: boolean | undefined
+	// The outage is not an API the child could not reach — a ship stop no relaunch answered, or a host
+	// restart that killed it — so it is left out of the run-wide streak.
+	is_streak_exempt?: boolean | undefined
+	// The exit record shows the session could not authenticate (`api-auth.ts`).
+	is_auth_failure?: boolean | undefined
 }
 
 const NO_SIGNALS: EndingSignals = { is_outage: false, is_cut: false }
@@ -73,12 +79,10 @@ function is_closed(state: IssueState): boolean {
 	return state.state.toUpperCase() === CLOSED_STATE
 }
 
-// A parked child is one a person still owns: it stopped for a decision (`needs-decision`) or it was
-// found already merged (`already-done`). Either way it is left alone and not counted as a failure.
-const PARK_LABELS: ReadonlyArray<string> = [NEEDS_DECISION_LABEL, ALREADY_DONE_LABEL]
-
+// A parked child is one a person still owns (`PARKED_LABELS`): it is left alone and not counted as a
+// failure again.
 function is_parked(state: IssueState): boolean {
-	return PARK_LABELS.some((label) => has_label_name(state.labels, label))
+	return has_parked_label(state.labels)
 }
 
 // **CLOSED means merged, whatever labels it carries** — a child that finished and merged keeps the
@@ -94,6 +98,8 @@ function unfinished_outcome(signals: EndingSignals): ChildOutcome {
 
 	if (signals.is_cut) return 'cut'
 
+	if (signals.is_auth_failure === true) return 'unauthenticated'
+
 	return signals.is_outage ? 'outage' : 'failed'
 }
 
@@ -107,12 +113,16 @@ function open_outcome(state: IssueState, signals: EndingSignals): ChildOutcome {
 	return unfinished_outcome(signals)
 }
 
-// The signals are read by the CLI and matter only for an OPEN child — a CLOSED child is merged
-// regardless of how the process exited.
+// The signals are read by the CLI and, but for a withdrawal, matter only for an OPEN child — a CLOSED
+// child is merged regardless of how the process exited. **A withdrawal is read first**: `lane:withdraw`
+// records it before stopping the child and leaves the issue OPEN, which would otherwise read as a child
+// to resume or park.
 function classify_child(
 	state: IssueState | undefined,
 	signals: EndingSignals = NO_SIGNALS,
 ): ChildOutcome {
+	if (signals.is_withdrawn === true) return 'withdrawn'
+
 	if (state === undefined) return 'unresolved'
 
 	if (is_closed(state)) return 'merged'
@@ -121,9 +131,9 @@ function classify_child(
 }
 
 // The counter change a child's outcome implies. A merge counts a merge (which resets the failure
-// streak); a failure counts a failure; a split, parked or human-review child counts nothing — a decision
-// waiting on a person is not the environment failing — and `undefined` says the carry record is left
-// untouched.
+// streak); a failure counts a failure; a split, parked, withdrawn or human-review child counts nothing —
+// a decision a person made or still owes is not the environment failing — and `undefined` says the
+// carry record is left untouched.
 function change_of(outcome: ChildOutcome): CarryChange | undefined {
 	if (outcome === 'merged') return { merged: ONE }
 
@@ -161,7 +171,7 @@ function counters_comment(carry: RunCarry): string {
 }
 
 // Why the run parked a child it judged failed. A child that stops itself leaves its own comment; one
-// the driver stops leaves none, so this tells a person why it carries `needs-decision`.
+// the driver stops leaves none, so this tells a person why it carries `run:stalled`.
 // Script-emitted, so English.
 interface ParkReason {
 	child: string
@@ -180,21 +190,22 @@ function park_comment(reason: ParkReason): string {
 	const transcript = reason.output === undefined ? '' : ` (\`${reason.output}\`)`
 
 	return [
-		'Parked with `needs-decision` by `pnpm josh run:merge`, the `backlogrun` driver — not by the child itself.',
+		`Parked with \`${RUN_STALLED_LABEL}\` by \`pnpm josh run:merge\`, the \`backlogrun\` driver — a mechanical failure, with no decision to make.`,
 		`- Why: ${reason.cause}`,
-		'- Read: the issue is OPEN, carries none of `needs-decision`, `already-done`, `needs-human-review` or `epic`, and no merged pull request’s `closes #N` names it.',
+		'- Read: the issue is OPEN, carries no park label, `needs-human-review` or `epic`, no merged pull request’s `closes #N` names it, and it declares no open blocker, start date still ahead or sample condition not yet met.',
 		streak_line(reason.carry),
-		`- Next: read the child’s transcript${transcript}, then either resume it with \`fullrun ${issue_cite.plain(reason.child)}\`, or record the decision here and remove \`needs-decision\`.`,
+		`- Next: read the child’s transcript${transcript}, ${run_stalled.next_step(reason.child)}.`,
 	].join('\n')
 }
 
-// Why the run released a child it would otherwise have parked: the child records open blockers, so
-// its order is already decided and it waits rather than asking a person. Script-emitted, so English.
-function waiting_comment(blockers: ReadonlyArray<string>): string {
+// Why the run released a child it would otherwise have parked: the child records open blockers or a
+// start date still ahead or samples still short, so when it runs is already decided and it waits rather than asking a person.
+// Script-emitted, so English.
+function waiting_comment(waits: ReadonlyArray<string>): string {
 	return [
 		'Released to wait by `pnpm josh run:merge`, the `backlogrun` driver — not parked, and not counted as a failure.',
-		`- Why: the child’s session ended unfinished while it records open blockers: ${blockers.join(', ')}.`,
-		'- Next: its order is already recorded — it becomes runnable again once its blockers merge; a blocker outside the backlog still needs a person to land it.',
+		`- Why: the child’s session ended unfinished while it waits on: ${waits.join(', ')}.`,
+		'- Next: when it runs is already recorded — it becomes runnable again once its blockers merge, its start date arrives and its sample condition is met; a blocker outside the backlog still needs a person to land it.',
 	].join('\n')
 }
 
@@ -210,5 +221,7 @@ const run_merge = {
 	is_outage_guard_tripped,
 }
 
-export type { ChildOutcome, EndingSignals, ParkReason }
+export type { EndingSignals, ParkReason }
 export { run_merge }
+
+export { type ChildOutcome } from './run-merge-outcome'

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

@@ -0,0 +1,91 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { git_gh_issue_write } from '#scripts/gh/git-gh-issue-write'
+import { issue_comment_cli, type CommentRequest } from '#scripts/issue/issue-comment-cli'
+import { NEEDS_DECISION_LABEL } from '#scripts/issue/issue-labels'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { issue_park } from '#scripts/issue/issue-park'
+import { session_cite } from '#scripts/issue/session-cite'
+import { cli_flags } from '#scripts/lib/cli-flags'
+import { run_park } from './run-park'
+
+// `josh run:park <N> --body-file <path>` — park a lane child for a person's decision in one call: the
+// question as a comment, `needs-decision`, and the local record the `lane-park` guard reads.
+// `josh run:park <N> --clear` takes the park back off once the decision is recorded.
+//
+// **The park was two hand-typed commands, and a child could stop after either one**
+// (joshuafolkken/kit#4132). One call writes both, and only a park that has both is recorded, so the
+// guard falls silent on exactly the child that left a question behind.
+//
+// **`in-progress` and the hold are not this command's.** A parked child keeps `in-progress`, and every
+// parked ending still owes `pnpm josh run:release <N>` (`backlogrun-park.md` → "park and continue").
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const ARGV_OFFSET = 2
+const CLEAR_FLAG = '--clear'
+const USAGE = `Usage: josh run:park <issue-number> --body-file <path> | <issue-number> ${CLEAR_FLAG}`
+const CLEAR_OPTIONS = { clear: { type: 'boolean' } } as const
+
+function clear_issue(argv: ReadonlyArray<string>): string | undefined {
+	const parsed = cli_flags.arguments_of(argv, CLEAR_OPTIONS)
+
+	if (parsed === undefined) return undefined
+
+	return issue_number_shape.single_of(parsed.positionals)
+}
+
+async function park(request: CommentRequest, directory: string): Promise<number> {
+	const { issue_number, body } = request
+	const write = await issue_park.apply(issue_number, NEEDS_DECISION_LABEL, body)
+	const is_parked = write.is_labelled && write.is_commented
+	const is_recorded = is_parked && run_park.record(issue_number, directory)
+
+	console.info(
+		`park ${session_cite.issue(issue_number)} — label: ${String(write.is_labelled)} · comment: ${String(write.is_commented)} · recorded: ${String(is_recorded)}`,
+	)
+
+	return is_parked ? SUCCESS_EXIT_CODE : FAILURE_EXIT_CODE
+}
+
+// **The record goes whatever the label answers**: the decision is a person's and already made, so a
+// guard reading a stale park would only stay silent on the child's next stop.
+async function clear(issue_number: string, directory: string): Promise<number> {
+	run_park.clear(issue_number, directory)
+	const is_cleared = await git_gh_issue_write.issue_clear_label(issue_number, NEEDS_DECISION_LABEL)
+
+	console.info(`park ${session_cite.issue(issue_number)} — cleared: ${String(is_cleared)}`)
+
+	return is_cleared ? SUCCESS_EXIT_CODE : FAILURE_EXIT_CODE
+}
+
+async function run_clear(argv: ReadonlyArray<string>, directory: string): Promise<number> {
+	const issue_number = clear_issue(argv)
+
+	if (issue_number !== undefined) return await clear(issue_number, directory)
+
+	console.error(USAGE)
+
+	return FAILURE_EXIT_CODE
+}
+
+async function run(
+	argv: ReadonlyArray<string>,
+	directory: string = process.cwd(),
+): Promise<number> {
+	if (argv.includes(CLEAR_FLAG)) return await run_clear(argv, directory)
+
+	const request = issue_comment_cli.resolve_request(argv, USAGE)
+
+	return request === undefined ? FAILURE_EXIT_CODE : await park(request, directory)
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const run_park_cli = { USAGE, run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { run_park_cli }

package/scripts/run/park/run-park.ts

@@ -0,0 +1,88 @@
+import { backlog_budget } from '#scripts/backlog/backlog-budget'
+import { git_common_directory } from '#scripts/git/git-common-directory'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { stamp_record, type StampRecordSpec } from '#scripts/josh/stamp-record'
+import { json_value } from '#scripts/lib/json-value'
+import { z } from 'zod'
+
+// The local record of a lane child's park — the half of `run:park` a `PreToolUse` guard can read.
+//
+// **The park itself is a GitHub label, which a synchronous guard cannot read**, so `lane-park` used to
+// fire on every lane-child stop, parked or not (joshuafolkken/kit#4132). `run:park` writes this record
+// once the comment and the label are both on the issue, and the guard reads it back synchronously, the
+// way the pre-gate cut guard reads `run-cut.ts`'s record.
+//
+// **Keyed to the repository and the issue, not the work tree.** The child parks from its lane, and the
+// parent clears the park from the main checkout once a person has decided; both resolve the same
+// common git directory, so `run:park --clear` removes the record wherever it runs.
+//
+// **Bounded like the cut record, and taken back by the next dispatch.** The guard asks within the run
+// that parked, seconds after the park; a label a person removed by hand, without `--clear`, must not
+// leave the guard silent on that issue's next dispatch, so `lane:dispatch` clears the record before it
+// starts the child, and a record past the lane child's idle bound reads as no park.
+
+const PARK_PREFIX = 'josh-run-park-'
+const PARK_MAX_AGE_MS = backlog_budget.DEFAULT_IDLE_MS
+
+const run_park_schema = z.object({
+	issue: z.string(),
+	parked_at: z.string(),
+})
+
+type RunPark = z.infer<typeof run_park_schema>
+
+function parse_park(raw: string): RunPark | undefined {
+	return json_value.parse_with(raw, run_park_schema)
+}
+
+function parked_at_of(park: RunPark): string {
+	return park.parked_at
+}
+
+const PARK_SPEC: StampRecordSpec<RunPark> = {
+	parse: parse_park,
+	timestamp_of: parked_at_of,
+	max_age_ms: PARK_MAX_AGE_MS,
+}
+
+function park_path(repository: string, issue: string): string {
+	return stamp_file.stamp_path(`${PARK_PREFIX}${issue}-`, repository)
+}
+
+// **The directory is injectable so a test never writes the live record** — the same reason
+// `run_cut.carried_cut_sync` takes one.
+function record(issue: string, directory: string, now: Date = new Date()): boolean {
+	const repository = git_common_directory.repository(directory)
+
+	if (repository === undefined) return false
+
+	stamp_file.replace_stamp(park_path(repository, issue), { issue, parked_at: now.toISOString() })
+
+	return true
+}
+
+function clear(issue: string, directory: string): void {
+	const repository = git_common_directory.repository(directory)
+
+	if (repository !== undefined) stamp_file.remove_stamp(park_path(repository, issue))
+}
+
+// **A fault reads as "not parked"**, the direction `carried_cut_sync` takes: the guard then speaks once,
+// which a child answers by reissuing, rather than falling silent on a run that never parked.
+function is_parked_sync(issue: string, directory: string, now: Date = new Date()): boolean {
+	const repository = git_common_directory.repository(directory)
+
+	if (repository === undefined) return false
+
+	const read = stamp_record.classify(
+		stamp_file.read_stamp_text(park_path(repository, issue)),
+		PARK_SPEC,
+		now,
+	)
+
+	return read.kind === 'carried' && read.record.issue === issue
+}
+
+const run_park = { PARK_MAX_AGE_MS, clear, is_parked_sync, record }
+
+export { run_park }

package/scripts/run/park/run-stalled.ts

@@ -0,0 +1,68 @@
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { RUN_STALLED_LABEL } from '#scripts/issue/issue-labels'
+
+// What a `run:stalled` park says, written and read in one place (joshuafolkken/kit#4215): the park
+// event carries the cause's short name after the label, the park comment its whole `Why:`, and the
+// park comments, `backlog:plan --waves` and `run:board` name the one next action.
+
+// Why a child was parked: `short` rides on the park event and the board row, `why` on the comment.
+interface StallCause {
+	short: string
+	why: string
+}
+
+// What `run:merge` judged when it parks a child with no ship stop to name.
+const SESSION_UNFINISHED: StallCause = {
+	short: 'session unfinished',
+	why: 'the child’s session ended with its issue still open and unfinished.',
+}
+const CUT_NOT_RELAUNCHED: StallCause = {
+	short: 'cut not relaunched',
+	why: 'its lane held a declared cut, but no successor could be relaunched from it (or it already was once).',
+}
+
+const RESUME_COMMAND = 'fullrun'
+const CAUSE_LEAD = `${RUN_STALLED_LABEL}: `
+const NEXT_ARROW = ' → '
+
+function resume_of(child: number | string): string {
+	return `${RESUME_COMMAND} ${issue_cite.plain(child)}`
+}
+
+// The next action as a clause, which a park comment's `Next:` and the plan's note end with.
+function next_step(child: number | string): string {
+	return `fix the cause, then resume it with \`${resume_of(child)}\` or remove \`${RUN_STALLED_LABEL}\` to offer it again`
+}
+
+function park_event(child: number | string, cause: string): string {
+	return `${issue_cite.plain(child)} parked (${CAUSE_LEAD}${cause})`
+}
+
+// The cause a park event's reason carries: `''` for a bare `run:stalled` (written before the event
+// carried one), `undefined` for a reason that is no `run:stalled` park.
+function cause_of(reason: string): string | undefined {
+	if (reason === RUN_STALLED_LABEL) return ''
+
+	return reason.startsWith(CAUSE_LEAD) ? reason.slice(CAUSE_LEAD.length) : undefined
+}
+
+// A stalled row's right end: its cause, then the action that resumes it — the action alone where no
+// cause was recorded.
+function row_text(child: number | string, cause = ''): string {
+	const resume = resume_of(child)
+
+	return cause === '' ? resume : `${cause}${NEXT_ARROW}${resume}`
+}
+
+const run_stalled = {
+	CUT_NOT_RELAUNCHED,
+	SESSION_UNFINISHED,
+	cause_of,
+	next_step,
+	park_event,
+	resume_of,
+	row_text,
+}
+
+export { run_stalled }
+export type { StallCause }

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

@@ -0,0 +1,73 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { cli_flags } from '#scripts/lib/cli-flags'
+import { run_pause, type PauseRequest, type PauseResult, type StepReport } from './run-pause'
+
+// `josh run:pause <M> --for <N>` — the argument parsing and the report around `run-pause.ts`. One
+// line per step that landed; a failure names its step, what was already done, and the rerun that
+// continues from there.
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const ARGV_OFFSET = 2
+const USAGE = 'Usage: josh run:pause <issue> --for <prerequisite>'
+const OPTIONS = { for: { type: 'string' } } as const
+
+// The prerequisite has to be another issue: `#M` blocked by itself is no order at all.
+function prerequisite_of(value: string | undefined, issue: string): string | undefined {
+	if (value === undefined || value === issue) return undefined
+
+	return issue_number_shape.is_issue_number(value) ? value : undefined
+}
+
+function parse_request(argv: ReadonlyArray<string>): PauseRequest | undefined {
+	const parsed = cli_flags.arguments_of(argv, OPTIONS)
+	if (parsed === undefined) return undefined
+	const issue = issue_number_shape.single_of(parsed.positionals)
+	const prerequisite = issue === undefined ? undefined : prerequisite_of(parsed.values.for, issue)
+
+	return issue === undefined || prerequisite === undefined ? undefined : { issue, prerequisite }
+}
+
+function report_done(done: ReadonlyArray<StepReport>): void {
+	for (const { step, detail } of done) console.info(`${step}: ${detail}`)
+}
+
+function report_failure(request: PauseRequest, result: PauseResult & { kind: 'failed' }): void {
+	const steps = result.done.map(({ step }) => step).join(', ')
+
+	console.error(`✖ ${result.step} failed: ${result.reason}`)
+	console.error(`Done: ${steps.length === 0 ? 'nothing' : steps}.`)
+	console.error(
+		`Rerun \`pnpm josh run:pause ${request.issue} --for ${request.prerequisite}\` to continue from ${result.step}.`,
+	)
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const request = parse_request(argv)
+
+	if (request === undefined) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const result = await run_pause.pause(request)
+
+	report_done(result.done)
+	if (result.kind === 'paused') return SUCCESS_EXIT_CODE
+	report_failure(request, result)
+
+	return FAILURE_EXIT_CODE
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const run_pause_cli = { USAGE, run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { run_pause_cli }