@joshuafolkken/kit 1.1471.0 → 1.1514.0

package/scripts/lane/lane-session-broker.ts

@@ -1,23 +1,14 @@
 import { randomUUID } from 'node:crypto'
-import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
+import { mkdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
 import { setTimeout as sleep } from 'node:timers/promises'
-import { agent_argv } from '#scripts/agent/agent-argv'
-import { agent_role_profile, type AgentProvider } from '#scripts/agent/agent-role-profile'
 import { git_common_directory } from '#scripts/git/git-common-directory'
 import { stamp_file } from '#scripts/josh/stamp-file'
-import { error_text } from '#scripts/lib/error-message'
 import { json_value } from '#scripts/lib/json-value'
-import { detached_launch } from '#scripts/run/detached-launch'
-import { run_ship_review } from '#scripts/run/ship/run-ship-review'
-import { run_ship_stage } from '#scripts/run/ship/run-ship-stage'
 import { z } from 'zod'
 import { lane_broker_server, type BrokerServer } from './lane-broker-server'
-import { lane_child_invocation, type ShipStop } from './lane-child-invocation'
-import { lane_child_marker } from './lane-child-marker'
-import { lane_parked } from './lane-parked'
 import type { LaneInfo } from './lane-registry'
-import { lane_relaunch } from './lane-relaunch'
+import { lane_session_action, type BrokerAction, type BrokerAnswer } from './lane-session-action'
 
 // The sessions a lane child's detached `josh ship` cannot start itself, started for it by a process
 // that can: the round-1 and round-2 reviewer, and the fresh child a stopped ship hands back to. An
@@ -25,13 +16,11 @@ import { lane_relaunch } from './lane-relaunch'
 // Claude lane is served by the `run:wake` supervisor (`claude-lane-broker.ts`), because Claude Code removes its
 // token from what its Bash tool starts, so a token-only credential never reaches the ship the child
 // launched (joshuafolkken/kit#3817). **The request names an action, never a command**: the server
-// rebuilds the argv from the registered lane, so a child can ask for nothing but these two sessions.
+// rebuilds the argv from the registered lane, so a child can ask for nothing but these two sessions
+// (`lane-session-action.ts`).
 
 const REQUEST_PREFIX = '.josh-review-request-'
 const RESPONSE_PREFIX = '.josh-review-response-'
-const BRIEF_PREFIX = 'josh-ship-review-brief-'
-const FINDINGS_PREFIX = 'josh-ship-review-findings-'
-const LOG_PREFIX = 'josh-ship-review-log-'
 const CACHE_DIRECTORY = ['node_modules', '.cache']
 const POLL_MS = 100
 // The heartbeat is kept for a ship branched before the server record, and read only where a
@@ -41,22 +30,8 @@ const LEGACY_HEARTBEAT_LIMIT_MS = 3000
 const MINUTE_MS = 60_000
 const REQUEST_LIMIT_MINUTES = 30
 const REQUEST_LIMIT_MS = REQUEST_LIMIT_MINUTES * MINUTE_MS
-const ANTHROPIC_PROVIDER: AgentProvider = 'anthropic'
-const stop_schema = z
-	.object({
-		stage: z.enum(run_ship_stage.STAGE),
-		title: z.string(),
-		flags: z.array(z.string()).readonly(),
-		is_review: z.boolean(),
-		conflicts: z.array(z.string()).readonly().default([]),
-	})
-	.strict()
-const action_schema = z.discriminatedUnion('kind', [
-	z.object({ kind: z.literal('review'), round: z.enum(['1', '2']) }).strict(),
-	z.object({ kind: z.literal('relaunch'), stop: stop_schema }).strict(),
-])
 const request_schema = z
-	.object({ session: z.uuid(), nonce: z.uuid(), action: action_schema })
+	.object({ session: z.uuid(), nonce: z.uuid(), action: lane_session_action.action_schema })
 	.strict()
 const response_schema = z
 	.object({
@@ -66,18 +41,13 @@ const response_schema = z
 		heartbeat_at: z.number().int().positive(),
 	})
 	.strict()
+// **A failure's reason sits beside the response, never in it**: a ship branched before the reason parses
+// the response strictly, so a new field would read as no server (joshuafolkken/kit#3974).
+const reason_schema = z.object({ nonce: z.string(), reason: z.string() }).strict()
 type BrokerRequest = z.infer<typeof request_schema>
 type BrokerResponse = z.infer<typeof response_schema>
-type ReviewRound = Extract<z.infer<typeof action_schema>, { kind: 'review' }>['round']
-type BrokerAction = { kind: 'review'; round: ReviewRound } | { kind: 'relaunch'; stop: ShipStop }
-
-function review_paths(directory: string): { brief: string; findings: string; log: string } {
-	return {
-		brief: stamp_file.stamp_path(BRIEF_PREFIX, directory, '.md'),
-		findings: stamp_file.stamp_path(FINDINGS_PREFIX, directory, '.txt'),
-		log: stamp_file.stamp_path(LOG_PREFIX, directory, '.log'),
-	}
-}
+
+const { failure } = lane_session_action
 
 function request_path(directory: string, issue: string): string {
 	return path.join(directory, ...CACHE_DIRECTORY, `${REQUEST_PREFIX}${issue}.json`)
@@ -90,6 +60,10 @@ function response_path(directory: string, issue: string): string | undefined {
 	return path.join(path.dirname(common), ...CACHE_DIRECTORY, `${RESPONSE_PREFIX}${issue}.json`)
 }
 
+function reason_path(response: string): string {
+	return `${response}.reason`
+}
+
 function read_record<T>(target: string, schema: z.ZodType<T>): T | undefined {
 	try {
 		return json_value.parse_with(readFileSync(target, 'utf8'), schema)
@@ -98,102 +72,25 @@ function read_record<T>(target: string, schema: z.ZodType<T>): T | undefined {
 	}
 }
 
-// The reviewer runs on the lane's own provider, so a Claude lane's server never starts a Codex reviewer
-// and an OpenAI lane's never starts a Claude one.
-function provider_of(lane: LaneInfo): AgentProvider {
-	return lane.profile?.provider ?? ANTHROPIC_PROVIDER
-}
-
-// **The reviewer carries the lane's mark explicitly**: the supervisor serving a Claude lane is no lane child,
-// so a reviewer inheriting its environment would descend from the carry record's owner unmarked and be
-// read as the `backlogrun` parent by every hook. **Its prompt ends with the review invocation**, so the
-// lane's liveness read and the park's reap find it as they find the child (joshuafolkken/kit#3878).
-
-function review_prompt(lane: LaneInfo, round: ReviewRound): string {
-	const target = review_paths(lane.directory)
-	const prompt_of =
-		round === '1' ? run_ship_review.reviewer_prompt : run_ship_review.verification_prompt
-	const tail = lane_child_invocation.review_invocation(lane.issue)
-
-	return `${prompt_of(target.brief, target.findings, lane.issue)} This is ${tail}`
-}
-
-async function launch_review(lane: LaneInfo, round: ReviewRound): Promise<boolean> {
-	const target = review_paths(lane.directory)
-	const built = agent_argv.resolve_in(
-		review_prompt(lane, round),
-		agent_role_profile.REVIEWER,
-		lane.directory,
-	)
-	if (built.kind === 'rejected' || built.profile.provider !== provider_of(lane)) return false
-
-	const result = await detached_launch.launch_attached(
-		{
-			argv: built.argv,
-			cwd: lane.directory,
-			log_path: target.log,
-			profile: built.profile,
-			env: lane_child_marker.env_for(lane.issue),
-		},
-		console.error,
-	)
-
-	return result.kind === 'completed' && result.exit_code === 0
-}
-
-// An OpenAI lane's successor is its supervisor's to start, never a relaunch's.
-function relaunch(lane: LaneInfo, stop: ShipStop): boolean {
-	if (lane_relaunch.is_openai_lane(lane)) return false
-
-	const invocation = lane_child_invocation.ship_stop_invocation(lane.issue, stop)
-	const phase = agent_role_profile.IMPLEMENTATION_PHASE
-	const result = lane_relaunch.relaunch(lane, invocation, phase, console.error)
-
-	return result.kind === 'launched'
-}
-
-// **A parked issue gets no session**: a request can be read long after it was written, so the park is
-// read when the action runs, never when it was asked for (joshuafolkken/kit#3878).
-async function perform(lane: LaneInfo, action: BrokerAction): Promise<boolean> {
-	if (await lane_parked.is_parked(lane.issue)) return false
-
-	if (action.kind === 'relaunch') return relaunch(lane, action.stop)
-
-	return await launch_review(lane, action.round)
-}
-
-function write_response(target: string, body: BrokerResponse): void {
+function write_record(target: string, body: BrokerResponse | z.infer<typeof reason_schema>): void {
 	const temporary = `${target}.${String(process.pid)}.tmp`
 
 	writeFileSync(temporary, JSON.stringify(body))
 	renameSync(temporary, target)
 }
 
-async function launched(lane: LaneInfo, action: BrokerAction): Promise<boolean> {
-	try {
-		return await perform(lane, action)
-	} catch (error) {
-		error_text.trace_swallowed('lane_session_broker.launched', error)
-
-		return false
-	}
-}
-
 async function process_request(
 	lane: LaneInfo,
 	response: string,
 	received: BrokerRequest,
 	state: { current: BrokerResponse },
 ): Promise<void> {
-	const is_success = await launched(lane, received.action)
+	const answer = await lane_session_action.answer(lane, received.action)
+	const { session, nonce } = received
 
-	state.current = {
-		session: received.session,
-		nonce: received.nonce,
-		is_success,
-		heartbeat_at: Date.now(),
-	}
-	write_response(response, state.current)
+	if (!answer.is_success) write_record(reason_path(response), { nonce, reason: answer.reason })
+	state.current = { session, nonce, is_success: answer.is_success, heartbeat_at: Date.now() }
+	write_record(response, state.current)
 }
 
 async function serve(
@@ -236,7 +133,7 @@ function prepare(lane: LaneInfo): { response: string; current: BrokerResponse }
 		heartbeat_at: Date.now(),
 	}
 
-	write_response(response, current)
+	write_record(response, current)
 
 	return { response, current }
 }
@@ -244,7 +141,7 @@ function prepare(lane: LaneInfo): { response: string; current: BrokerResponse }
 function start_heartbeat(state: { current: BrokerResponse }, response: string): NodeJS.Timeout {
 	const heartbeat = setInterval(() => {
 		state.current = { ...state.current, heartbeat_at: Date.now() }
-		write_response(response, state.current)
+		write_record(response, state.current)
 	}, LEGACY_HEARTBEAT_MS)
 
 	heartbeat.unref()
@@ -264,6 +161,7 @@ async function stop_server(
 	await serving
 	clearInterval(heartbeat)
 	unlinkSync(response)
+	rmSync(reason_path(response), { force: true })
 	lane_broker_server.remove(response)
 }
 
@@ -306,31 +204,47 @@ function session_response(target: string, session: string): BrokerResponse | und
 	return response?.session === session ? response : undefined
 }
 
+// A failure from a server that predates the reason leaves none.
+function answer_of(target: string, response: BrokerResponse): BrokerAnswer {
+	if (response.is_success) return lane_session_action.SUCCESS
+
+	const record = read_record(reason_path(target), reason_schema)
+	const reason = record?.nonce === response.nonce ? record.reason : 'it gave no reason'
+
+	return failure(`the broker answered a failure: ${reason}`)
+}
+
+// The server's answer to this request, or `undefined` while it is still being served.
 function response_verdict(
 	target: string,
 	session: string,
 	nonce: string,
-): 'wait' | 'success' | 'failure' {
+): BrokerAnswer | undefined {
 	const response = session_response(target, session)
 
-	if (!is_live_response(target, response, lane_broker_server.is_running)) return 'failure'
-	if (response.nonce !== nonce) return 'wait'
+	if (!is_live_response(target, response, lane_broker_server.is_running)) {
+		return failure('the broker stopped serving before it answered')
+	}
 
-	return response.is_success ? 'success' : 'failure'
+	return response.nonce === nonce ? answer_of(target, response) : undefined
 }
 
-async function wait_response(target: string, session: string, nonce: string): Promise<boolean> {
+async function wait_response(
+	target: string,
+	session: string,
+	nonce: string,
+): Promise<BrokerAnswer> {
 	const deadline = Date.now() + REQUEST_LIMIT_MS
 
 	while (Date.now() < deadline) {
 		const verdict = response_verdict(target, session, nonce)
-		if (verdict !== 'wait') return verdict === 'success'
+		if (verdict !== undefined) return verdict
 
 		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
 		await sleep(POLL_MS)
 	}
 
-	return false
+	return failure(`the broker gave no answer within ${String(REQUEST_LIMIT_MINUTES)} minutes`)
 }
 
 function live_response(target: string): BrokerResponse | undefined {
@@ -356,22 +270,26 @@ function withdraw(pending: string, nonce: string): void {
 	if (read_record(pending, request_schema)?.nonce === nonce) stamp_file.remove_stamp(pending)
 }
 
-async function request(directory: string, issue: string, action: BrokerAction): Promise<boolean> {
+async function request(
+	directory: string,
+	issue: string,
+	action: BrokerAction,
+): Promise<BrokerAnswer> {
 	const target = response_path(directory, issue)
 	const response = target === undefined ? undefined : live_response(target)
 
-	if (target === undefined || response === undefined) return false
+	if (target === undefined || response === undefined) return failure('no broker serves this lane')
 
 	const nonce = randomUUID()
 	const body = { session: response.session, nonce, action }
 	const pending = request_path(directory, issue)
 
 	stamp_file.replace_stamp(pending, body)
-	const is_success = await wait_response(target, response.session, nonce)
+	const answer = await wait_response(target, response.session, nonce)
 
 	withdraw(pending, nonce)
 
-	return is_success
+	return answer
 }
 
 const lane_session_broker = {
@@ -379,9 +297,10 @@ const lane_session_broker = {
 	request,
 	request_path,
 	response_path,
-	review_paths,
+	review_paths: lane_session_action.review_paths,
 	with_server,
 }
 
-export type { BrokerAction, ReviewRound }
 export { lane_session_broker }
+
+export { type ReviewRound, type BrokerAction, type BrokerAnswer } from './lane-session-action'

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

@@ -0,0 +1,71 @@
+#!/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 { lane_withdraw, type WithdrawOutcome } from './lane-withdraw'
+
+// `josh lane:withdraw <issue> --reason <text>` — every explanation on standard error, and a withdrawal
+// that did not end with the Issue closed exits non-zero, so a caller never takes a half-done one as done.
+
+const ARGV_OFFSET = 2
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const USAGE = 'Usage: josh lane:withdraw <issue-number> --reason <text>'
+const OPTIONS = { reason: { type: 'string' } } as const
+
+interface Request {
+	issue: string
+	reason: string
+}
+
+function issue_of(positionals: ReadonlyArray<string>): string | undefined {
+	const [issue, ...rest] = positionals
+
+	return rest.length === 0 && issue_number_shape.is_issue_number(issue ?? '') ? issue : undefined
+}
+
+// A reason of only whitespace is no reason: the Issue would close with an empty `Why:` line.
+function reason_of(value: unknown): string | undefined {
+	const reason = cli_flags.string_of(value)?.trim()
+
+	return reason === '' ? undefined : reason
+}
+
+function parse_request(argv: ReadonlyArray<string>): Request | undefined {
+	const parsed = cli_flags.arguments_of(argv, OPTIONS)
+	if (parsed === undefined) return undefined
+	const issue = issue_of(parsed.positionals)
+	const reason = reason_of(parsed.values.reason)
+
+	return issue === undefined || reason === undefined ? undefined : { issue, reason }
+}
+
+function exit_code_of(outcome: WithdrawOutcome): number {
+	return outcome.kind === 'withdrawn' && outcome.is_closed ? SUCCESS_EXIT_CODE : FAILURE_EXIT_CODE
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const request = parse_request(argv)
+
+	if (request === undefined) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const outcome = await lane_withdraw.withdraw(request.issue, request.reason)
+
+	console.error(lane_withdraw.describe(outcome, request.issue))
+
+	return exit_code_of(outcome)
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const lane_withdraw_cli = { run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { lane_withdraw_cli }

package/scripts/lane/lane-withdraw.ts

@@ -0,0 +1,182 @@
+import { git_gh_issue_write } from '#scripts/gh/git-gh-issue-write'
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { issue_state_cli } from '#scripts/issue/issue-state-cli'
+import { session_cite } from '#scripts/issue/session-cite'
+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_label } from '#scripts/run/run-label'
+import { lane_close, type CloseKind } from './lane-close'
+import { lane_preserve, type KeptWork } from './lane-preserve'
+import { lane_reap } from './lane-reap'
+import { lane_registry, type LaneInfo } from './lane-registry'
+
+// `josh lane:withdraw <N> --reason <text>` — a person takes a running lane child's issue out of the run
+// for good: the child is stopped, its work stashed, the Issue closed as not planned and the lane closed.
+//
+// **The `withdraw` event is written first, before anything is stopped.** Killing the child alone would
+// let `lane:await` book it stopped and `run:merge` classify it from GitHub — an open issue resumed as an
+// `outage` or parked `needs-decision`. `run:merge` reads the event stream before GitHub, so a child whose
+// newest launch-or-withdraw event is a withdraw is booked `withdrawn` whatever the Issue's state reads
+// at that moment, and the race between the kill and the close cannot book it as anything else.
+//
+// **The issue is read again once the child is stopped.** It may merge between the first read and the
+// reap; the reap stopped it, so the second read is final, and an issue it already closed keeps
+// GitHub's close — `run:merge` books a merged close as merged whatever the event stream says.
+//
+// A tree that could not be stashed is left in place with the Issue open: closing the lane would delete
+// the work, and the person decides what to keep.
+
+const WITHDRAW_OCCASION = 'lane withdraw'
+const WITHDRAW_CAUSE = 'a person withdrew it with `lane:withdraw`'
+const CLOSED_STATE = 'CLOSED'
+const CLOSED_KIND = 'closed'
+const NO_LANE_KIND = 'no-lane'
+const UNREADABLE_KIND = 'unreadable'
+
+type Unsaved = Extract<KeptWork, { kind: 'unsaved' }>
+
+interface Withdrawn {
+	kind: 'withdrawn'
+	// How many of the child's processes the withdrawal stopped — 0 for a child that had already ended.
+	reaped: number
+	stash: string | undefined
+	is_closed: boolean
+	// The issue had closed on its own — merged — before the withdrawal reached it, so it was left as is.
+	had_closed: boolean
+	lane: CloseKind
+}
+
+type IssueSettled = Pick<Withdrawn, 'had_closed' | 'is_closed'>
+
+type Refused =
+	{ kind: typeof CLOSED_KIND } | { kind: typeof NO_LANE_KIND } | { kind: typeof UNREADABLE_KIND }
+type WithdrawOutcome = Withdrawn | Unsaved | Refused
+
+function close_comment(reason: string): string {
+	return [
+		'Withdrawn by a person with `pnpm josh lane:withdraw`.',
+		'Its lane child was stopped and the lane closed.',
+		`- Why: ${reason}`,
+	].join('\n')
+}
+
+async function record_withdraw(issue: string, reason: string): Promise<void> {
+	await run_event_stream_emit.emit(
+		run_event_stream.EVENT_KIND.WITHDRAW,
+		`${issue_cite.plain(issue)} withdrawn by a person: ${reason}`,
+	)
+}
+
+// A closed issue has nothing to withdraw, and an unread one might be: neither writes anything.
+async function refusal_of(issue: string): Promise<Refused | undefined> {
+	const read = await issue_state_cli.read_issue(issue)
+
+	if (read.kind !== 'state') return { kind: UNREADABLE_KIND }
+	if (read.state.state.toUpperCase() === CLOSED_STATE) return { kind: CLOSED_KIND }
+
+	return undefined
+}
+
+async function close_open_issue(issue: string, reason: string): Promise<IssueSettled> {
+	const refusal = await refusal_of(issue)
+
+	// An unread issue may have merged during the reap, so it is left open for a person to close.
+	if (refusal !== undefined) {
+		const is_closed = refusal.kind === CLOSED_KIND
+
+		return { is_closed, had_closed: is_closed }
+	}
+
+	const is_closed = await git_gh_issue_write.issue_close_not_planned(issue, close_comment(reason))
+
+	return { is_closed, had_closed: false }
+}
+
+async function close_issue(
+	issue: string,
+	reason: string,
+	stash: string | undefined,
+): Promise<IssueSettled> {
+	const settled = await close_open_issue(issue, reason)
+
+	if (stash !== undefined) await lane_preserve.announce(issue, stash, WITHDRAW_CAUSE)
+	await run_label.unmark(issue)
+
+	return settled
+}
+
+async function stop_and_close(lane: LaneInfo, reason: string): Promise<WithdrawOutcome> {
+	await record_withdraw(lane.issue, reason)
+	const reaped = lane_reap.reap_child(lane.issue).length
+	const saved = await lane_preserve.keep_work(lane.issue, lane.directory, WITHDRAW_OCCASION)
+
+	if (saved.kind === 'unsaved') return saved
+	const settled = await close_issue(lane.issue, reason, saved.stash)
+	const closed = await lane_close.close_lane(lane.issue)
+
+	return { kind: 'withdrawn', reaped, stash: saved.stash, ...settled, lane: closed.kind }
+}
+
+/** Stop `#<N>`'s lane child, stash its work, close the Issue as not planned and close the lane. */
+async function withdraw(issue: string, reason: string): Promise<WithdrawOutcome> {
+	issue_number_shape.require_issue_number(issue)
+	const refusal = await refusal_of(issue)
+
+	if (refusal !== undefined) return refusal
+	const lane = await lane_registry.find_open_lane(issue)
+
+	if (lane === undefined) return { kind: NO_LANE_KIND }
+
+	return await stop_and_close(lane, reason)
+}
+
+function stash_sentence(stash: string | undefined): string {
+	if (stash === undefined) return 'The lane held no uncommitted work.'
+
+	return `Its uncommitted work was stashed — recover with \`pnpm josh stash:pop "${stash}"\`.`
+}
+
+function withdrawn_text(outcome: Withdrawn, issue: string): string {
+	const cited = session_cite.issue(issue)
+	const stopped = outcome.reaped === 0 ? 'Its child had already ended.' : 'Stopped its child.'
+	const head = `Withdrew ${cited}. ${stopped} ${stash_sentence(outcome.stash)}`
+	const lane = outcome.lane === 'incomplete' ? ' The lane could not be fully removed.' : ''
+
+	if (outcome.had_closed) return `${head} The Issue had already closed and was left as is.${lane}`
+
+	if (outcome.is_closed) return `${head} The Issue is closed as not planned.${lane}`
+
+	return `${head} The Issue could not be closed — close ${cited} by hand; \`run:merge\` books it withdrawn either way.${lane}`
+}
+
+function unsaved_text(outcome: Unsaved, issue: string): string {
+	return `The child for ${session_cite.issue(issue)} was stopped, but its uncommitted work could not be stashed (${outcome.reason}), so the Issue is left open and the lane at ${outcome.directory}; \`run:merge\` books it withdrawn.`
+}
+
+function refused_text(outcome: Refused, issue: string): string {
+	const cited = session_cite.issue(issue)
+
+	if (outcome.kind === CLOSED_KIND) {
+		return `${cited} is already closed, so there is nothing to withdraw.`
+	}
+
+	if (outcome.kind === NO_LANE_KIND) {
+		return `No lane is open for ${cited}, so there is no child to withdraw.`
+	}
+
+	return `The state of ${cited} could not be read, so nothing was stopped or closed — try again.`
+}
+
+function describe(outcome: WithdrawOutcome, issue: string): string {
+	if (outcome.kind === 'unsaved') return unsaved_text(outcome, issue)
+
+	return outcome.kind === 'withdrawn'
+		? withdrawn_text(outcome, issue)
+		: refused_text(outcome, issue)
+}
+
+const lane_withdraw = { describe, withdraw }
+
+export type { WithdrawOutcome }
+export { lane_withdraw }

package/scripts/lint/format.ts

@@ -1,14 +1,14 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { project_checks } from '#scripts/gate/project-checks'
-import { ESLINT_CACHE_FLAGS } from '#scripts/josh/josh-command-types'
+import { ESLINT_CACHE_FLAGS, PRETTIER_CACHE_FLAGS } from '#scripts/josh/josh-command-types'
 import { composite_arguments, USAGE_ERROR_EXIT_CODE } from '#scripts/josh/josh-composite-arguments'
 import { execa } from 'execa'
 
 const COMMAND_NAME = 'format'
 const ARGV_OFFSET = 2
 const FAIL_EXIT_CODE = 1
-const PRETTIER_ARGS = ['exec', 'prettier', '--write', '.'] as const
+const PRETTIER_WRITE_ARGS = ['exec', 'prettier', '--write', '.', ...PRETTIER_CACHE_FLAGS] as const
 const ESLINT_FIX_ARGS = ['exec', 'eslint', '.', '--fix', ...ESLINT_CACHE_FLAGS] as const
 
 async function run_step(args: ReadonlyArray<string>, directory: string): Promise<number> {
@@ -37,7 +37,7 @@ async function run_format(directory: string): Promise<number> {
 	const prettier_exit_code = await run_unless_skipped(
 		'prettier',
 		prettier_reason,
-		PRETTIER_ARGS,
+		PRETTIER_WRITE_ARGS,
 		directory,
 	)
 	if (prettier_exit_code !== 0) return prettier_exit_code
@@ -64,4 +64,4 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
 
 const format = { run, run_format }
 
-export { ESLINT_FIX_ARGS, format }
+export { ESLINT_FIX_ARGS, format, PRETTIER_WRITE_ARGS }

package/scripts/lint/lint-parallel.ts

@@ -1,7 +1,11 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { project_checks } from '#scripts/gate/project-checks'
-import { ESLINT_CACHE_FILE, ESLINT_CACHE_FLAGS } from '#scripts/josh/josh-command-types'
+import {
+	ESLINT_CACHE_FILE,
+	ESLINT_CACHE_FLAGS,
+	PRETTIER_CACHE_FLAGS,
+} from '#scripts/josh/josh-command-types'
 import { lane_cache_run } from '#scripts/lane/lane-cache-run'
 import {
 	buffered_process,
@@ -11,7 +15,6 @@ import {
 import { SKIP_MARKER } from '#scripts/test/skip-marker'
 import { cross_file_recheck, type CrossFileRecheckOptions } from './cross-file-recheck'
 
-const PRETTIER_ARGS = ['exec', 'prettier', '--check', '.'] as const
 // This — not the `lint:eslint` map entry — is the eslint invocation `josh gate` reaches, so the
 // cache flags come from the same constant the ignore rules are asserted against.
 // A copy here would keep writing the old location the day that constant
@@ -23,6 +26,10 @@ const WHOLE_TREE_RECHECK: CrossFileRecheckOptions = {
 	patterns: [WHOLE_TREE],
 }
 
+// Prettier's cache stays this checkout's own, never shared through `lane_cache_run` as eslint's is:
+// its entries do not survive a move (`josh-command-types.ts` → `GATE_CACHE_SPECS`).
+const PRETTIER_ARGS = ['exec', 'prettier', '--check', WHOLE_TREE, ...PRETTIER_CACHE_FLAGS] as const
+
 // What one eslint run is made of: the child's arguments, and what re-reading a cached cross-file report
 // (`cross-file-recheck.ts`) needs to ask the same question again — the cache file and the targets.
 interface EslintRun {
@@ -132,4 +139,4 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
 
 const lint_parallel = { run_lint_checks, run_lint_parallel_checks }
 
-export { ESLINT_ARGS, lint_parallel }
+export { ESLINT_ARGS, lint_parallel, PRETTIER_ARGS }

package/scripts/lint/lint-related-scope.ts

@@ -8,6 +8,7 @@ import {
 import {
 	ESLINT_RELATED_CACHE_FILE,
 	ESLINT_RELATED_CACHE_FLAGS,
+	PRETTIER_RELATED_CACHE_FLAGS,
 } from '#scripts/josh/josh-command-types'
 import type { CrossFileRecheckOptions } from './cross-file-recheck'
 
@@ -94,8 +95,10 @@ function describe_scope(scope: ChangedFileScope, root: string): string {
 	return changed_file_scope.describe_scope(scope, root, VOCABULARY)
 }
 
+// The scoped run's own cache file, for the reason eslint's below gives: prettier too rewrites its
+// cache file whole, so a narrowed run sharing the gate's would discard entries a concurrent gate wrote.
 function prettier_arguments(files: ReadonlyArray<string>): ReadonlyArray<string> {
-	return [...PRETTIER_ARGS, ...files]
+	return [...PRETTIER_ARGS, ...files, ...PRETTIER_RELATED_CACHE_FLAGS]
 }
 
 // The cache file is this command's own rather than the gate's, because the two run at the same time.