@joshuafolkken/kit 1.1383.0 → 1.1435.0

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

@@ -0,0 +1,51 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { lane_dispatch } from './lane-dispatch'
+import { lane_restart, type RestartOutcome } from './lane-restart'
+
+// `josh lane:restart <issue>` — the contract `lane:dispatch` sets: the fresh child's pid is the one
+// token on standard output, every explanation on standard error, and a restart that did not start a
+// fresh child exits non-zero. A failed dispatch is warned off-screen exactly as `lane:dispatch` warns it,
+// since the stopped child is then left for `run:merge` to collect.
+
+const ARGV_OFFSET = 2
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const USAGE = 'Usage: josh lane:restart <issue-number>'
+
+async function report(outcome: RestartOutcome, issue: string): Promise<number> {
+	console.error(lane_restart.describe(outcome, issue))
+
+	if (outcome.kind !== 'restarted') return FAILURE_EXIT_CODE
+	const { dispatch } = outcome
+
+	if (lane_dispatch.is_worth_warning(dispatch)) await lane_dispatch.warn_of_problem(dispatch, issue)
+	if (dispatch.kind !== 'dispatched') return FAILURE_EXIT_CODE
+
+	console.info(String(dispatch.pid))
+
+	return SUCCESS_EXIT_CODE
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const issue = argv.length === 1 ? argv[0] : undefined
+
+	if (issue === undefined || !issue_number_shape.is_issue_number(issue)) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	return await report(await lane_restart.restart(issue), issue)
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const lane_restart_cli = { run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { lane_restart_cli }

package/scripts/lane/lane-restart.ts

@@ -0,0 +1,175 @@
+import { git_stash } from '#scripts/git/stash/git-stash'
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { IN_PROGRESS_LABEL } from '#scripts/issue/issue-labels'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { session_cite } from '#scripts/issue/session-cite'
+import { error_text } from '#scripts/lib/error-message'
+import { run_cut } from '#scripts/run/cut/run-cut'
+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 { lane_dispatch, type DispatchOutcome } from './lane-dispatch'
+import { lane_preserve } from './lane-preserve'
+import { lane_reap } from './lane-reap'
+import { lane_registry, type LaneInfo } from './lane-registry'
+
+// `josh lane:restart <N>` — a person stops a running lane child and starts its issue over in a fresh
+// session, typically after correcting the Issue's specification mid-run.
+//
+// **The restart is a hand-off inside the parent's re-confirm window, not a recovery.** Killing the child
+// alone would let `lane:await` book it stopped and `run:merge` classify it — an `outage` resumes the old
+// session with the old specification in mind, anything else is parked `needs-decision` and counted as a
+// failure. `run:cut` already hands a lane to a new process inside `lane:await`'s re-confirm window, so a
+// child that disappears and reappears under the same `fullrun #<N>` pattern is never collected: the
+// restart stops, stashes and re-dispatches within that window, and no failure or outage is counted.
+//
+// **No GitHub round-trip sits between the stop and the launch**, since one slow answer would outlast the
+// window. The `in-progress` marker is claimed while the old child still runs — a refused claim stops
+// nothing — and the Issue comment naming the stash is posted after the fresh child is up.
+//
+// The fresh dispatch reads no exit record (an outage record would otherwise resume the stopped session),
+// a carried cut is ended (its successor would adopt the old hand-off), and the work in the tree is
+// stashed with the recovery line on the Issue. The `restart` event follows the dispatch's own
+// `child-launch`, so the stream and `run:board` say a person restarted the child.
+
+const RESTART_OCCASION = 'lane restart'
+const RESTART_CAUSE = 'a person restarted its child with `lane:restart`'
+const DISPATCHED_KIND = 'dispatched'
+const NO_LANE_KIND = 'no-lane'
+const NOT_RUNNING_KIND = 'not-running'
+const UNCLAIMED_KIND = 'unclaimed'
+
+interface Unsaved {
+	kind: 'unsaved'
+	directory: string
+	reason: string
+}
+
+interface Restarted {
+	kind: 'restarted'
+	dispatch: DispatchOutcome
+	stash: string | undefined
+}
+
+type Refused =
+	| { kind: typeof NO_LANE_KIND }
+	| { kind: typeof NOT_RUNNING_KIND }
+	| { kind: typeof UNCLAIMED_KIND; reason: string }
+type RestartOutcome = Restarted | Unsaved | Refused
+type Saved = Unsaved | { kind: 'saved'; stash: string | undefined }
+
+// A cut the stopped child carried would hand its successor the old session's hand-off at
+// `run:cut --resume`; the fresh session has to start from the Issue instead.
+function end_carried_cut(lane: LaneInfo): void {
+	const carried = run_cut.lane_cut_sync(lane.directory)
+
+	if (carried !== undefined) run_cut.end_cut(carried.target)
+}
+
+async function stash_of(lane: LaneInfo): Promise<string | undefined> {
+	if (!(await git_stash.has_changes(lane.directory))) return undefined
+
+	return await lane_preserve.push_work(lane.issue, lane.directory, RESTART_OCCASION)
+}
+
+// A tree that could not be read or pushed is left as it is: re-dispatching into it would hand the fresh
+// session the stopped one's half-done work as though it were its own.
+async function save_work(lane: LaneInfo): Promise<Saved> {
+	try {
+		return { kind: 'saved', stash: await stash_of(lane) }
+	} catch (error) {
+		return { kind: 'unsaved', directory: lane.directory, reason: error_text.message_of(error) }
+	}
+}
+
+async function record_restart(issue: string): Promise<void> {
+	await run_event_stream_emit.emit(
+		run_event_stream.EVENT_KIND.RESTART,
+		`${issue_cite.plain(issue)} restarted in a fresh session by a person`,
+	)
+}
+
+async function relaunch(lane: LaneInfo): Promise<RestartOutcome> {
+	end_carried_cut(lane)
+	const saved = await save_work(lane)
+
+	if (saved.kind === 'unsaved') return saved
+	const dispatch = await lane_dispatch.dispatch_child(lane.issue, 'restart')
+
+	if (dispatch.kind === DISPATCHED_KIND) await record_restart(lane.issue)
+
+	if (saved.stash !== undefined) {
+		await lane_preserve.announce(lane.issue, saved.stash, RESTART_CAUSE)
+	}
+
+	return { kind: 'restarted', dispatch, stash: saved.stash }
+}
+
+// A child that ended on its own during the claim (say, right after merging its PR) is a finished child
+// for `run:merge` to collect — relaunching it would re-run a done issue inside the re-confirm window.
+async function stop_and_relaunch(lane: LaneInfo): Promise<RestartOutcome> {
+	if (lane_reap.reap_child(lane.issue).length === 0) return { kind: NOT_RUNNING_KIND }
+
+	return await relaunch(lane)
+}
+
+/** Stop the running child of `#<N>`'s lane and re-dispatch the issue there in a fresh session. */
+async function restart(issue: string): Promise<RestartOutcome> {
+	issue_number_shape.require_issue_number(issue)
+	const lane = await lane_registry.find_open_lane(issue)
+
+	if (lane === undefined) return { kind: NO_LANE_KIND }
+	if (!lane_reap.is_child_running(issue)) return { kind: NOT_RUNNING_KIND }
+	const claim = await lane_dispatch.claim_marker(issue)
+
+	if (!claim.is_applied) return { kind: UNCLAIMED_KIND, reason: claim.reason }
+
+	return await stop_and_relaunch(lane)
+}
+
+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}"\`.`
+}
+
+// A dispatch that failed leaves the stopped child to `run:merge`: nothing re-appeared inside the
+// re-confirm window, so the parent collects it as it would any stopped child.
+function restarted_text(outcome: Restarted, issue: string): string {
+	const head = `Stopped the child for ${session_cite.issue(issue)}. ${stash_sentence(outcome.stash)}`
+	const dispatch = lane_dispatch.describe(outcome.dispatch, issue)
+
+	if (outcome.dispatch.kind === DISPATCHED_KIND) return `${head} ${dispatch}`
+
+	return `${head} The fresh dispatch failed, so \`run:merge\` will collect the stopped child: ${dispatch}`
+}
+
+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 nothing was re-dispatched and the lane is left at ${outcome.directory}; \`run:merge\` will collect the stopped child.`
+}
+
+function refused_text(outcome: Refused, issue: string): string {
+	const cited = session_cite.issue(issue)
+
+	if (outcome.kind === NO_LANE_KIND) {
+		return `No lane is open for ${cited}, so there is no child to restart.`
+	}
+
+	if (outcome.kind === UNCLAIMED_KIND) {
+		return `The \`${IN_PROGRESS_LABEL}\` label could not be confirmed on ${cited} (${outcome.reason}), so the running child was left as it is — nothing was stopped or re-dispatched.`
+	}
+
+	return `No child is running in the lane for ${cited}, so nothing was stopped or re-dispatched — a child that has already ended is \`run:merge\`'s to collect.`
+}
+
+function describe(outcome: RestartOutcome, issue: string): string {
+	if (outcome.kind === 'unsaved') return unsaved_text(outcome, issue)
+
+	return outcome.kind === 'restarted'
+		? restarted_text(outcome, issue)
+		: refused_text(outcome, issue)
+}
+
+const lane_restart = { describe, restart }
+
+export type { RestartOutcome }
+export { lane_restart }

package/scripts/lane/{openai-review-broker.ts → lane-session-broker.ts}

@@ -3,15 +3,27 @@ import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from '
 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 } from '#scripts/agent/agent-role-profile'
+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_child_invocation, type ShipStop } from './lane-child-invocation'
+import { lane_child_marker } from './lane-child-marker'
 import type { LaneInfo } from './lane-registry'
+import { lane_relaunch } from './lane-relaunch'
+
+// 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
+// OpenAI lane's own supervisor serves it, because a nested Codex cannot write outside its sandbox; a
+// 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.
 
 const REQUEST_PREFIX = '.josh-review-request-'
 const RESPONSE_PREFIX = '.josh-review-response-'
@@ -25,8 +37,22 @@ const 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(), round: z.enum(['1', '2']) })
+	.object({ session: z.uuid(), nonce: z.uuid(), action: action_schema })
 	.strict()
 const response_schema = z
 	.object({
@@ -36,9 +62,10 @@ const response_schema = z
 		heartbeat_at: z.number().int().positive(),
 	})
 	.strict()
-type ReviewRequest = z.infer<typeof request_schema>
-type ReviewResponse = z.infer<typeof response_schema>
-type ReviewRound = ReviewRequest['round']
+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 {
@@ -67,6 +94,16 @@ 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.
+
 async function launch_review(lane: LaneInfo, round: ReviewRound): Promise<boolean> {
 	const target = review_paths(lane.directory)
 	const prompt_of =
@@ -76,7 +113,7 @@ async function launch_review(lane: LaneInfo, round: ReviewRound): Promise<boolea
 		agent_role_profile.REVIEWER,
 		lane.directory,
 	)
-	if (built.kind === 'rejected' || built.profile.provider !== 'openai') return false
+	if (built.kind === 'rejected' || built.profile.provider !== provider_of(lane)) return false
 
 	const result = await detached_launch.launch_attached(
 		{
@@ -84,6 +121,7 @@ async function launch_review(lane: LaneInfo, round: ReviewRound): Promise<boolea
 			cwd: lane.directory,
 			log_path: target.log,
 			profile: built.profile,
+			env: lane_child_marker.env_for(lane.issue),
 		},
 		console.error,
 	)
@@ -91,18 +129,35 @@ async function launch_review(lane: LaneInfo, round: ReviewRound): Promise<boolea
 	return result.kind === 'completed' && result.exit_code === 0
 }
 
-function write_response(target: string, body: z.infer<typeof response_schema>): void {
+// 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'
+}
+
+async function perform(lane: LaneInfo, action: BrokerAction): Promise<boolean> {
+	if (action.kind === 'relaunch') return relaunch(lane, action.stop)
+
+	return await launch_review(lane, action.round)
+}
+
+function write_response(target: string, body: BrokerResponse): void {
 	const temporary = `${target}.${String(process.pid)}.tmp`
 
 	writeFileSync(temporary, JSON.stringify(body))
 	renameSync(temporary, target)
 }
 
-async function launched(lane: LaneInfo, round: ReviewRound): Promise<boolean> {
+async function launched(lane: LaneInfo, action: BrokerAction): Promise<boolean> {
 	try {
-		return await launch_review(lane, round)
+		return await perform(lane, action)
 	} catch (error) {
-		error_text.trace_swallowed('openai_review_broker.launched', error)
+		error_text.trace_swallowed('lane_session_broker.launched', error)
 
 		return false
 	}
@@ -111,10 +166,10 @@ async function launched(lane: LaneInfo, round: ReviewRound): Promise<boolean> {
 async function process_request(
 	lane: LaneInfo,
 	response: string,
-	received: ReviewRequest,
-	state: { current: ReviewResponse },
+	received: BrokerRequest,
+	state: { current: BrokerResponse },
 ): Promise<void> {
-	const is_success = await launched(lane, received.round)
+	const is_success = await launched(lane, received.action)
 
 	state.current = {
 		session: received.session,
@@ -129,7 +184,7 @@ async function serve(
 	lane: LaneInfo,
 	session: string,
 	response: string,
-	state: { is_running: boolean; current: ReviewResponse },
+	state: { is_running: boolean; current: BrokerResponse },
 ): Promise<void> {
 	let last_nonce = ''
 	const target = request_path(lane.directory, lane.issue)
@@ -148,7 +203,7 @@ async function serve(
 	}
 }
 
-function prepare(lane: LaneInfo): { response: string; current: ReviewResponse } {
+function prepare(lane: LaneInfo): { response: string; current: BrokerResponse } {
 	const response = response_path(lane.directory, lane.issue)
 	if (response === undefined) throw new Error('review broker has no trusted response location')
 
@@ -156,7 +211,7 @@ function prepare(lane: LaneInfo): { response: string; current: ReviewResponse }
 
 	mkdirSync(path.dirname(response), { recursive: true })
 	mkdirSync(path.dirname(request_path(lane.directory, lane.issue)), { recursive: true })
-	const current: ReviewResponse = {
+	const current: BrokerResponse = {
 		session,
 		nonce: '',
 		is_success: false,
@@ -168,7 +223,7 @@ function prepare(lane: LaneInfo): { response: string; current: ReviewResponse }
 	return { response, current }
 }
 
-function start_heartbeat(state: { current: ReviewResponse }, response: string): NodeJS.Timeout {
+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)
@@ -179,15 +234,17 @@ function start_heartbeat(state: { current: ReviewResponse }, response: string):
 	return heartbeat
 }
 
+// **The heartbeat outlives the request being served.** A ship waiting on a reviewer reads a stale
+// heartbeat as a dead server, so stopping it first would fail a review the server is still running.
 async function stop_server(
 	state: { is_running: boolean },
 	heartbeat: NodeJS.Timeout,
 	serving: Promise<void>,
 	response: string,
 ): Promise<void> {
-	clearInterval(heartbeat)
 	state.is_running = false
 	await serving
+	clearInterval(heartbeat)
 	unlinkSync(response)
 }
 
@@ -205,9 +262,9 @@ async function with_server<T>(lane: LaneInfo, run: () => Promise<T>): Promise<T>
 }
 
 function is_live_response(
-	response: ReviewResponse | undefined,
+	response: BrokerResponse | undefined,
 	session: string,
-): response is ReviewResponse {
+): response is BrokerResponse {
 	const now = Date.now()
 
 	return (
@@ -218,7 +275,7 @@ function is_live_response(
 }
 
 function response_verdict(
-	response: ReviewResponse | undefined,
+	response: BrokerResponse | undefined,
 	session: string,
 	nonce: string,
 ): 'wait' | 'success' | 'failure' {
@@ -242,21 +299,42 @@ async function wait_response(target: string, session: string, nonce: string): Pr
 	return false
 }
 
-async function request(directory: string, issue: string, round: ReviewRound): Promise<boolean> {
-	const target = response_path(directory, issue)
-	if (target === undefined) return false
+function live_response(target: string): BrokerResponse | undefined {
 	const response = read_record(target, response_schema)
 
-	if (response === undefined || !is_live_response(response, response.session)) return false
+	return is_live_response(response, response?.session ?? '') ? response : undefined
+}
+
+// Whether a server answers for this lane now — what a Claude lane's ship asks before it hands a session
+// over rather than starting the session itself.
+function is_serving(directory: string, issue: string): boolean {
+	const target = response_path(directory, issue)
+
+	return target !== undefined && live_response(target) !== undefined
+}
+
+async function request(directory: string, issue: string, action: BrokerAction): Promise<boolean> {
+	const target = response_path(directory, issue)
+	const response = target === undefined ? undefined : live_response(target)
+
+	if (target === undefined || response === undefined) return false
 
 	const nonce = randomUUID()
-	const body: ReviewRequest = { session: response.session, nonce, round }
+	const body = { session: response.session, nonce, action }
 
 	stamp_file.replace_stamp(request_path(directory, issue), body)
 
 	return await wait_response(target, response.session, nonce)
 }
 
-const openai_review_broker = { request, request_path, response_path, review_paths, with_server }
+const lane_session_broker = {
+	is_serving,
+	request,
+	request_path,
+	response_path,
+	review_paths,
+	with_server,
+}
 
-export { openai_review_broker }
+export type { BrokerAction, ReviewRound }
+export { lane_session_broker }