@joshuafolkken/kit 1.872.0

package/scripts/lane/lane-start-point.ts

@@ -0,0 +1,175 @@
+import { git_command } from '#scripts/git/git-command'
+import { git_remote_branch } from '#scripts/git/git-remote-branch'
+
+// Where a lane is cut from (joshuafolkken/kit#1535).
+//
+// **The bare default-branch name is the wrong start point, because git resolves it to the *local*
+// `refs/heads/<default>` — a ref nothing in this workflow ever advances.** Merges happen on GitHub
+// through `pnpm josh followup`, and this repository's main work tree does not have the
+// default branch checked out, so there is no fast-forward for it to receive. It falls one commit
+// further behind on every merge, and a lane opened from it starts without the work that was just
+// merged. Measured on 2026-09-07: `refs/heads/main` was `e3a68c04` while `refs/remotes/origin/main`
+// was `78f746f9`.
+//
+// **The remote-tracking ref is the one that is current**, because a fetch updates it without anyone
+// checking anything out — which is exactly the property the local branch lacks. It is named in full
+// (`refs/remotes/origin/<default>`) rather than as `origin/<default>`, so a local branch that
+// happens to be called `origin/<default>` cannot capture the reading.
+
+const REFS_REMOTES_ORIGIN_PREFIX = 'refs/remotes/origin/'
+
+// A fetch *failure* is reported and stepped over rather than raised. `lane:open` has to keep working
+// with no network at all — offline, and on a clone with no `origin` — and what it degrades to is
+// whatever `origin/<default>` already holds, which is still never *behind* the local branch. Note
+// what this does not cover: `fetch_branch` runs through `git_spawn.read`, which sets no
+// timeout, so a connection that hangs rather than failing blocks here instead of degrading.
+async function refresh_default_branch(default_branch: string): Promise<void> {
+	try {
+		await git_command.fetch_branch(default_branch)
+	} catch {
+		console.error(
+			`Could not fetch origin/${default_branch}; opening the lane from the remote-tracking ref as it stands.`,
+		)
+	}
+}
+
+// Said out loud rather than taken quietly. The resolver answers the bare name for a repository with
+// no remote *and* for a `rev-parse` that failed, and the second reading puts the lane back on the
+// stale ref this module exists to avoid — so the fallback is never silent.
+function report_local_fallback(default_branch: string): void {
+	console.error(
+		`No ${REFS_REMOTES_ORIGIN_PREFIX}${default_branch} to cut the lane from; using the local ${default_branch}, which may be behind what has been merged.`,
+	)
+}
+
+/**
+ * The commit-ish `git worktree add` should branch a lane from.
+ *
+ * The ref itself comes from `git_command.default_branch_reference`, which `change_base` resolves through
+ * too — one resolution rather than two, so a lane is measured against the commit it was cut from.
+ * What is added here is the fetch, which belongs to opening a lane and not to reading a diff.
+ *
+ * Falls back to the bare default-branch name where no remote-tracking ref exists — a fresh
+ * `git init`, or a clone whose `origin` was removed. There the local branch is the only answer
+ * there is, and it is not stale, because nothing else is advancing past it.
+ */
+async function resolve(): Promise<string> {
+	const default_branch = await git_command.get_default_branch()
+
+	await refresh_default_branch(default_branch)
+
+	const start_point = await git_command.default_branch_reference()
+
+	if (!start_point.startsWith(REFS_REMOTES_ORIGIN_PREFIX)) report_local_fallback(default_branch)
+
+	return start_point
+}
+
+// **A branch that already exists is attached to, never cut afresh** (joshuafolkken/kit#1627). Its
+// commits are a child's finished work: `epicrun` leaves a lane's branch behind whenever a child is
+// parked after pushing, and `lane:close` deletes the local branch while the remote one and the pull
+// request stay. Cutting a new `<N>-lane` from the default branch there orphans both — and it did so
+// **silently**, because `worktree add -b` succeeds once the local branch is gone. The loud half of
+// the same defect was `fatal: a branch named '<N>-lane' already exists`, which at least stopped.
+//
+// The reuse is said out loud for the same reason the local fallback above is: a lane that starts on
+// somebody's pushed commits is not the lane a fresh open produces, and reading the two as one is how
+// the work gets overwritten.
+function report_reuse(branch_name: string, where: string): void {
+	console.error(
+		`Reusing the existing ${where} branch ${branch_name}; this lane starts at that branch's own commits rather than at the default branch.`,
+	)
+}
+
+// Said when the remote could not be consulted, so a lane that may be behind it is not mistaken for
+// one that is current. The ref is still used: the alternative is cutting a fresh branch over commits
+// somebody pushed, which is the silent failure this whole module exists to remove, and starting on a
+// stale ref is loud and recoverable where that is neither.
+function report_unverified(branch_name: string): void {
+	console.error(
+		`Could not refresh ${REFS_REMOTES_ORIGIN_PREFIX}${branch_name} from origin; using it as it stands, which may be behind the remote.`,
+	)
+}
+
+async function refresh_lane_branch(branch_name: string): Promise<void> {
+	try {
+		await git_command.fetch_branch(branch_name)
+	} catch {
+		console.error(`Could not fetch ${branch_name} from origin.`)
+	}
+}
+
+async function tracking_reference(branch_name: string): Promise<string | undefined> {
+	const names = await git_command.branch_names_remote(`origin/${branch_name}`)
+
+	return names.length > 0 ? `${REFS_REMOTES_ORIGIN_PREFIX}${branch_name}` : undefined
+}
+
+/**
+ * The ref for a branch origin still has — fetched first, so the lane starts at the tip rather than
+ * at whatever this checkout last saw.
+ *
+ * **A `present` answer is authoritative, so this arm never degrades to a new branch.** With the
+ * fetch failed and no remote-tracking ref to fall back on — a second machine, a fresh clone — a
+ * fall-through would cut `<N>-lane` from the default branch over commits origin demonstrably has,
+ * which is the silent orphan this module exists to prevent. The Issue asks for an explicit report
+ * in place of a silent new branch, and refusing is that report: both ways out are named, and
+ * `lane:open` already fails this way for a seat it cannot read and an install it cannot finish.
+ */
+async function present_reference(branch_name: string): Promise<string> {
+	await refresh_lane_branch(branch_name)
+
+	const reference = await tracking_reference(branch_name)
+
+	if (reference !== undefined) return reference
+
+	throw new Error(
+		`origin has ${branch_name}, but it could not be fetched, so this lane cannot be opened on the commits already pushed to it. Fetch it — \`git fetch origin ${branch_name}\` — and run \`pnpm josh lane:open\` again.`,
+	)
+}
+
+// `absent` is the one answer that refuses the ref: the branch is gone from origin, so a ref still
+// pointing at it is stale and the lane is cut from the default branch as any new one is. Why origin
+// itself is asked rather than the remote-tracking ref is `git_remote_branch`'s own comment
+// (joshuafolkken/kit#1641 moved the asking there, so `pnpm josh release` could reuse it).
+async function remote_reference_for(branch_name: string): Promise<string | undefined> {
+	const answer = await git_remote_branch.ask(branch_name)
+
+	if (answer === 'absent') return undefined
+	if (answer === 'present') return await present_reference(branch_name)
+
+	report_unverified(branch_name)
+
+	return await tracking_reference(branch_name)
+}
+
+/**
+ * What `git worktree add` should be given for a lane on `branch_name`.
+ *
+ * `undefined` means **attach**: the branch is already here, so the work tree is put on it and no
+ * branch is created. Every other answer is a commit-ish a new branch is cut from — the remote-tracking
+ * ref of the lane branch when only the remote has it, and the default branch's when neither does,
+ * which is the behavior every lane had before joshuafolkken/kit#1627.
+ *
+ * **Nothing here deletes a branch to simplify the call.** That is what would lose the commits this
+ * function exists to keep.
+ */
+async function resolve_for_branch(branch_name: string): Promise<string | undefined> {
+	if (await git_command.branch_exists(branch_name)) {
+		report_reuse(branch_name, 'local')
+
+		return undefined
+	}
+
+	const remote_reference = await remote_reference_for(branch_name)
+
+	if (remote_reference === undefined) return await resolve()
+
+	report_reuse(branch_name, 'origin')
+
+	return remote_reference
+}
+
+const lane_start_point = { resolve, resolve_for_branch }
+
+export { lane_start_point }

package/scripts/lane/openai-lane-supervisor-cli.ts

@@ -0,0 +1,32 @@
+#!/usr/bin/env tsx
+import { agent_role_profile, type AgentProfile } from '#scripts/agent/agent-role-profile'
+import { lane_registry } from './lane-registry'
+import { openai_lane_supervisor } from './openai-lane-supervisor'
+
+const ARGV_OFFSET = 2
+const [issue, nonce] = process.argv.slice(ARGV_OFFSET)
+
+function worker_profile(profile: AgentProfile | undefined): AgentProfile | undefined {
+	if (profile !== undefined) return profile
+	const resolved = agent_role_profile.resolve(agent_role_profile.WORKER)
+
+	return resolved.kind === 'profile' ? resolved.profile : undefined
+}
+
+function openai_profile(profile: AgentProfile | undefined): AgentProfile | undefined {
+	const worker = worker_profile(profile)
+
+	return worker?.provider === 'openai' ? worker : undefined
+}
+
+async function main(): Promise<number> {
+	if (issue === undefined || nonce === undefined) return 1
+	const lane = await lane_registry.find_open_lane(issue)
+	if (lane === undefined) return 1
+	const profile = openai_profile(lane.profile)
+	if (profile === undefined) return 1
+
+	return await openai_lane_supervisor.supervise(lane, profile, nonce)
+}
+
+process.exitCode = await main()

package/scripts/lane/openai-lane-supervisor-decision.ts

@@ -0,0 +1,63 @@
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { z } from 'zod'
+
+const DECISION_PREFIX = 'josh-openai-lane-supervisor-decision-'
+const APPROVAL_POLL_MS = 50
+const APPROVAL_POLL_LIMIT = 200
+const schema = z.object({
+	nonce: z.string(),
+	decision: z.enum(['approved', 'cancelled']),
+})
+
+type Decision = z.infer<typeof schema>
+
+function target(lane_directory: string, nonce: string): string {
+	return stamp_file.stamp_path(`${DECISION_PREFIX}${nonce}-`, lane_directory)
+}
+
+function read(lane_directory: string, nonce: string): Decision | undefined {
+	try {
+		const raw = stamp_file.read_stamp_text(target(lane_directory, nonce)) ?? ''
+		const value: unknown = JSON.parse(raw)
+
+		return schema.parse(value)
+	} catch {
+		return undefined
+	}
+}
+
+function decide(lane_directory: string, nonce: string, decision: Decision['decision']): boolean {
+	const value = { nonce, decision }
+
+	return (
+		stamp_file.create_stamp(target(lane_directory, nonce), value) ||
+		read(lane_directory, nonce)?.decision === decision
+	)
+}
+
+function approve(lane_directory: string, nonce: string): boolean {
+	return decide(lane_directory, nonce, 'approved')
+}
+
+function cancel(lane_directory: string, nonce: string): boolean {
+	return decide(lane_directory, nonce, 'cancelled')
+}
+
+async function is_approved(lane_directory: string, nonce: string): Promise<boolean> {
+	for (let attempt = 0; attempt < APPROVAL_POLL_LIMIT; attempt += 1) {
+		const decision = read(lane_directory, nonce)?.decision
+		if (decision !== undefined) return decision === 'approved'
+
+		await new Promise((resolve) => setTimeout(resolve, APPROVAL_POLL_MS))
+	}
+
+	return false
+}
+
+function remove(lane_directory: string, nonce: string): void {
+	stamp_file.remove_stamp(target(lane_directory, nonce))
+}
+
+const openai_lane_supervisor_decision = { approve, cancel, is_approved, remove, target }
+
+export { openai_lane_supervisor_decision }

package/scripts/lane/openai-lane-supervisor.ts

@@ -0,0 +1,337 @@
+import { randomUUID } from 'node:crypto'
+import { linkSync, statSync, unlinkSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { agent_argv } from '#scripts/agent/agent-argv'
+import type { AgentProfile } from '#scripts/agent/agent-role-profile'
+import { process_identity } from '#scripts/josh/process-identity'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { detached_launch, type LaunchArgv } from '#scripts/run/detached-launch'
+import { run_cut, type RunCut } from '#scripts/run/run-cut'
+import { z } from 'zod'
+import { lane_child_invocation } from './lane-child-invocation'
+import { lane_child_marker } from './lane-child-marker'
+import { lane_dispatch_log } from './lane-dispatch-log'
+import type { LaneInfo } from './lane-registry'
+import { openai_lane_supervisor_decision } from './openai-lane-supervisor-decision'
+
+const OWNER_PREFIX = 'josh-openai-lane-supervisor-'
+const STATE_PREFIX = 'josh-openai-lane-supervisor-state-'
+const CHILD_POLL_MS = 250
+const CLAIM_POLL_MS = 50
+const CLAIM_POLL_LIMIT = 40
+const SUPERVISOR_SCRIPT = fileURLToPath(new URL('openai-lane-supervisor-cli.ts', import.meta.url))
+const owner_schema = z.object({
+	issue: z.string(),
+	nonce: z.string(),
+	pid: z.number().int().positive(),
+	process_start: z.string().optional(),
+})
+const state_schema = z.object({
+	owner_nonce: z.string(),
+	child_pid: z.number().int().positive().optional(),
+	child_process_start: z.string().optional(),
+	epoch: z.number().int().nonnegative(),
+})
+
+type SupervisorOwner = z.infer<typeof owner_schema>
+type SupervisorState = z.infer<typeof state_schema>
+
+function marker_path(lane_directory: string): string {
+	return stamp_file.stamp_path(OWNER_PREFIX, lane_directory)
+}
+
+function state_path(lane_directory: string): string {
+	return stamp_file.stamp_path(STATE_PREFIX, lane_directory)
+}
+
+function parsed_stamp<T>(target: string, schema: z.ZodType<T>): T | undefined {
+	try {
+		const value: unknown = JSON.parse(stamp_file.read_stamp_text(target) ?? '')
+		const parsed = schema.safeParse(value)
+
+		return parsed.success ? parsed.data : undefined
+	} catch {
+		return undefined
+	}
+}
+
+function read(lane_directory: string): SupervisorOwner | undefined {
+	return parsed_stamp(marker_path(lane_directory), owner_schema)
+}
+
+function read_state(lane_directory: string, nonce: string): SupervisorState | undefined {
+	const state = parsed_stamp(state_path(lane_directory), state_schema)
+
+	return state?.owner_nonce === nonce ? state : undefined
+}
+
+function is_live(owner: SupervisorOwner): boolean {
+	return process_identity.is_same_process(owner.pid, owner.process_start) !== false
+}
+
+function active(lane_directory: string): SupervisorOwner | undefined {
+	const owner = read(lane_directory)
+
+	return owner !== undefined && is_live(owner) ? owner : undefined
+}
+
+async function wait_for_active(lane_directory: string): Promise<SupervisorOwner | undefined> {
+	for (let attempt = 0; attempt < CLAIM_POLL_LIMIT; attempt += 1) {
+		const owner = active(lane_directory)
+		if (owner !== undefined) return owner
+		await new Promise((resolve) => setTimeout(resolve, CLAIM_POLL_MS))
+	}
+
+	return undefined
+}
+
+// The hard link snapshots the exact owner inode. Several contenders may snapshot one stale owner,
+// but only one can unlink it; a contender arriving after a replacement sees different inodes and
+// cannot remove the new live owner.
+function remove_if_unchanged(target: string): void {
+	const snapshot = `${target}.${String(process.pid)}.${randomUUID()}`
+
+	try {
+		linkSync(target, snapshot)
+		const current = statSync(target)
+		const linked = statSync(snapshot)
+		if (current.dev === linked.dev && current.ino === linked.ino) unlinkSync(target)
+	} catch {
+		/* absence or replacement is resolved by the exclusive create below */
+	} finally {
+		stamp_file.remove_stamp(snapshot)
+	}
+}
+
+interface ChildIdentity {
+	pid: number
+	process_start?: string
+}
+
+function live_child(state: SupervisorState | undefined): ChildIdentity | undefined {
+	if (state?.child_pid === undefined) return undefined
+	const { child_pid, child_process_start } = state
+
+	if (process_identity.is_same_process(child_pid, child_process_start) === false) {
+		return undefined
+	}
+
+	return {
+		pid: child_pid,
+		...(child_process_start !== undefined && { process_start: child_process_start }),
+	}
+}
+
+function carried_child(
+	lane_directory: string,
+	owner: SupervisorOwner | undefined,
+): ChildIdentity | undefined {
+	if (owner === undefined) return undefined
+
+	return live_child(read_state(lane_directory, owner.nonce))
+}
+
+function remove_stale_owner(target: string, previous: SupervisorOwner | undefined): boolean {
+	if (previous !== undefined && is_live(previous)) return false
+	if (stamp_file.read_stamp_text(target) !== undefined) remove_if_unchanged(target)
+
+	return true
+}
+
+function claim(issue: string, lane_directory: string, nonce: string): SupervisorOwner | undefined {
+	const target = marker_path(lane_directory)
+	const previous = read(lane_directory)
+	if (!remove_stale_owner(target, previous)) return undefined
+	const child = carried_child(lane_directory, previous)
+	const owner = { issue, nonce, ...process_identity.own_fields() }
+	if (!stamp_file.create_stamp(target, owner)) return undefined
+	stamp_file.replace_stamp(state_path(lane_directory), {
+		owner_nonce: nonce,
+		epoch: 0,
+		...(child !== undefined && {
+			child_pid: child.pid,
+			...(child.process_start !== undefined && {
+				child_process_start: child.process_start,
+			}),
+		}),
+	})
+
+	return owner
+}
+
+function update(lane_directory: string, owner: SupervisorOwner, state: SupervisorState): void {
+	if (read(lane_directory)?.nonce !== owner.nonce) return
+	stamp_file.replace_stamp(state_path(lane_directory), state)
+}
+
+function release(lane_directory: string, nonce: string): void {
+	if (read(lane_directory)?.nonce !== nonce) return
+	stamp_file.remove_stamp(state_path(lane_directory))
+	stamp_file.remove_stamp(marker_path(lane_directory))
+	openai_lane_supervisor_decision.remove(lane_directory, nonce)
+}
+
+function handed_off(cut: RunCut | undefined, issue: string): boolean {
+	return (
+		cut?.is_handed_off === true &&
+		cut.issue === issue &&
+		cut.invocation === run_cut.invocation_for(issue)
+	)
+}
+
+async function standing_cut(issue: string): Promise<RunCut | undefined> {
+	const git_directory = await run_cut.worktree_directory()
+	if (git_directory === undefined) return undefined
+	const read_cut = run_cut.read_cut(run_cut.cut_path(git_directory))
+
+	return read_cut.kind === 'carried' && handed_off(read_cut.cut, issue) ? read_cut.cut : undefined
+}
+
+function child_argv(lane: LaneInfo, profile: AgentProfile, is_resume: boolean): LaunchArgv {
+	const invocation = is_resume
+		? lane_child_invocation.resume_invocation(lane.issue)
+		: lane_child_invocation.child_invocation(lane.issue)
+	const built = agent_argv.with_profile_in(invocation, profile, lane.directory)
+	if (built.kind === 'rejected') throw new Error(built.note)
+
+	return built.argv
+}
+
+const LAUNCH_FAILED_KIND = 'launch-failed'
+type ChildResult =
+	| { kind: 'completed' }
+	| { kind: 'abnormal'; note: string }
+	| { kind: typeof LAUNCH_FAILED_KIND; note: string }
+
+interface Generation {
+	epoch: number
+	is_resume: boolean
+	lane: LaneInfo
+	owner: SupervisorOwner
+	profile: AgentProfile
+}
+
+function record_child(generation: Generation, child_pid: number): void {
+	const { lane, owner, epoch } = generation
+	const child_process_start = process_identity.read_start(child_pid)
+
+	update(lane.directory, owner, {
+		owner_nonce: owner.nonce,
+		epoch,
+		child_pid,
+		...(child_process_start !== undefined && { child_process_start }),
+	})
+}
+
+function child_result(
+	result: Awaited<ReturnType<typeof detached_launch.launch_attached>>,
+): ChildResult {
+	if (result.kind === 'failed') return { kind: LAUNCH_FAILED_KIND, note: result.note }
+	if (result.exit_code === 0) return { kind: 'completed' }
+	const note = `OpenAI lane child exited abnormally (${String(result.exit_code)})`
+
+	console.error(note)
+
+	return { kind: 'abnormal', note }
+}
+
+async function run_child(generation: Generation): Promise<ChildResult> {
+	const { lane, profile, is_resume } = generation
+	const result = await detached_launch.launch_attached(
+		{
+			argv: child_argv(lane, profile, is_resume),
+			cwd: lane.directory,
+			log_path: lane_dispatch_log.default_log_path(lane),
+			profile,
+			env: lane_child_marker.env_for(lane.issue),
+		},
+		(note) => {
+			console.error(`OpenAI lane child launch: ${note}`)
+		},
+		(child_pid) => {
+			record_child(generation, child_pid)
+		},
+	)
+
+	return child_result(result)
+}
+
+async function run_generations(generation: Generation): Promise<number> {
+	const result = await run_child(generation)
+	if (result.kind === LAUNCH_FAILED_KIND) return 1
+
+	if ((await standing_cut(generation.lane.issue)) !== undefined) {
+		return await run_generations({ ...generation, epoch: generation.epoch + 1, is_resume: true })
+	}
+
+	if (result.kind === 'abnormal') return 1
+
+	return 0
+}
+
+async function wait_for_inherited_child(
+	child_pid: number,
+	child_process_start: string | undefined,
+): Promise<void> {
+	while (process_identity.is_same_process(child_pid, child_process_start) !== false) {
+		await new Promise((resolve) => setTimeout(resolve, CHILD_POLL_MS))
+	}
+}
+
+async function recovered_resume(lane: LaneInfo, nonce: string): Promise<boolean | undefined> {
+	const child_pid = read_state(lane.directory, nonce)?.child_pid
+	if (child_pid === undefined) return false
+	await wait_for_inherited_child(child_pid, read_state(lane.directory, nonce)?.child_process_start)
+
+	if ((await standing_cut(lane.issue)) === undefined) return undefined
+
+	return true
+}
+
+async function run_claimed(
+	lane: LaneInfo,
+	profile: AgentProfile,
+	owner: SupervisorOwner,
+): Promise<number> {
+	const is_recovered = await recovered_resume(lane, owner.nonce)
+	if (is_recovered === undefined) return 0
+	const is_resume = is_recovered || (await standing_cut(lane.issue)) !== undefined
+	const epoch = (read_state(lane.directory, owner.nonce)?.epoch ?? 0) + 1
+
+	return await run_generations({ lane, profile, owner, is_resume, epoch })
+}
+
+async function supervise(lane: LaneInfo, profile: AgentProfile, nonce: string): Promise<number> {
+	const owner = claim(lane.issue, lane.directory, nonce)
+	if (owner === undefined) return 0
+
+	try {
+		if (!(await openai_lane_supervisor_decision.is_approved(lane.directory, nonce))) return 0
+
+		return await run_claimed(lane, profile, owner)
+	} finally {
+		release(lane.directory, nonce)
+	}
+}
+
+function supervisor_argv(issue: string, nonce: string): LaunchArgv {
+	return { command: process.execPath, args: [...process.execArgv, SUPERVISOR_SCRIPT, issue, nonce] }
+}
+
+const openai_lane_supervisor = {
+	active,
+	approve: openai_lane_supervisor_decision.approve,
+	cancel: openai_lane_supervisor_decision.cancel,
+	claim,
+	decision_path: openai_lane_supervisor_decision.target,
+	marker_path,
+	new_nonce: randomUUID,
+	read,
+	release,
+	state_path,
+	supervise,
+	supervisor_argv,
+	wait_for_active,
+}
+
+export { openai_lane_supervisor }