@joshuafolkken/kit 1.2114.0 → 1.3000.0

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

@@ -0,0 +1,320 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import {
+	agent_provider,
+	type AgentEnvironment,
+	type AgentProvider,
+} from '#scripts/agent/agent-provider'
+import { agent_session_environment } from '#scripts/josh/agent-session-environment'
+import { cli_body } from '#scripts/josh/cli-body'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { lane_child_marker } from '#scripts/lane/lane-child-marker'
+import { run_carry } from '#scripts/run/carry/run-carry'
+import {
+	detached_launch,
+	type AttachedLaunchResult,
+	type LaunchRequest,
+	type LaunchResult,
+} from '#scripts/run/detached-launch'
+import { run_hold, type HoldRead } from '#scripts/run/hold/run-hold'
+import { run_hold_block } from '#scripts/run/hold/run-hold-block'
+import { execa } from 'execa'
+import { run_handoff_args, type WorkflowHandoff } from './run-handoff-args'
+import { run_handoff_final } from './run-handoff-final'
+import { run_handoff_launch, type BuiltArgv } from './run-handoff-launch'
+import { run_handoff_retrospective } from './run-handoff-retrospective'
+
+// `josh run:handoff <keyword> [N|new ...] --brief-file <path>` — hand a workflow keyword typed in a
+// consultation session to a child session on the kit role profile's model, on the main session's own
+// provider. `kickoff` is waited for and its final message and URLs printed; `fullrun` / `halfrun` /
+// `prrun` are started in the background and handed back as a log and `run:progress --once`. `backlogrun` is
+// `josh backlogrun` itself, which already starts its parent on the scheduler profile.
+
+const ARGV_OFFSET = 2
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const AGENT_FLAG = '--agent'
+const LONE_FLAGS: ReadonlySet<string> = new Set(['--stop', '--restart'])
+const ISSUE_TOKEN = /#(\d+)/u
+const USAGE =
+	'Usage: josh run:handoff kickoff|fullrun|halfrun|prrun [N|new ...] --brief-file <path> | retrospective | backlogrun [...]'
+// `josh backlogrun --agent` names a provider by its CLI.
+const AGENT_NAMES: Readonly<Record<AgentProvider, string>> = {
+	anthropic: 'claude',
+	openai: 'codex',
+}
+
+interface HandoffPorts {
+	environment: AgentEnvironment
+	cwd: string
+	now: () => number
+	repository_directory: () => Promise<string | undefined>
+	tree_hold: () => Promise<HoldRead>
+	read_text: (target: string) => string | undefined
+	launch: (request: LaunchRequest) => LaunchResult
+	launch_attached: (request: LaunchRequest) => Promise<AttachedLaunchResult>
+	backlogrun: (argv: ReadonlyArray<string>) => Promise<number>
+	// Whether the carry record under this git directory marks the retrospective as run.
+	is_retrospective_done: (git_directory: string) => boolean
+	write: (line: string) => void
+}
+
+interface StartInput {
+	handoff: WorkflowHandoff
+	provider: AgentProvider
+	brief: string
+	git_directory: string
+}
+
+interface Started {
+	handoff: WorkflowHandoff
+	built: BuiltArgv
+	request: LaunchRequest
+	log: string
+	git_directory: string
+}
+
+type StartResult = { kind: 'started'; started: Started } | { kind: 'refused'; note: string }
+
+function note_to_stderr(note: string): void {
+	console.error(`run:handoff: ${note}`)
+}
+
+// `josh backlogrun` runs as its own command, so it loads its `.env` and owns its output; its CLI module
+// is an entry, never imported (`scripts/build/main-guard-boundary.test.ts`).
+async function josh_backlogrun(argv: ReadonlyArray<string>): Promise<number> {
+	const result = await execa('pnpm', ['josh', 'backlogrun', ...argv], {
+		stdio: 'inherit',
+		reject: false,
+	})
+
+	return result.exitCode ?? FAILURE_EXIT_CODE
+}
+
+// The hold `run:entry` claims for this working tree; an unknown tree reads as unreadable, never free.
+async function tree_hold(): Promise<HoldRead> {
+	const directory = await run_hold.worktree_directory()
+
+	if (directory === undefined) return { kind: 'unreadable' }
+
+	return run_hold.read_hold(run_hold.hold_path(directory))
+}
+
+const LIVE_PORTS: HandoffPorts = {
+	environment: process.env,
+	cwd: process.cwd(),
+	now: () => Date.now(),
+	repository_directory: run_carry.repository_directory,
+	tree_hold,
+	read_text: (target) => stamp_file.read_stamp_text(target),
+	launch: (request) => detached_launch.launch(request, note_to_stderr),
+	launch_attached: async (request) =>
+		await detached_launch.launch_attached(request, note_to_stderr),
+	backlogrun: josh_backlogrun,
+	is_retrospective_done: (git_directory) =>
+		run_carry.retrospective_done_of(run_carry.read_carry(run_carry.carry_path(git_directory))),
+	write: (line) => process.stdout.write(`${line}\n`),
+}
+
+function refuse(note: string, ports: HandoffPorts): number {
+	ports.write(`run:handoff: ${note}`)
+
+	return FAILURE_EXIT_CODE
+}
+
+// `--stop` / `--restart` stand alone in `josh backlogrun` (`backlogrun-args.ts`), so they take no `--agent`.
+function with_agent(rest: ReadonlyArray<string>, provider: AgentProvider): ReadonlyArray<string> {
+	const is_kept = rest.includes(AGENT_FLAG) || rest.some((token) => LONE_FLAGS.has(token))
+
+	return is_kept ? rest : [...rest, AGENT_FLAG, AGENT_NAMES[provider]]
+}
+
+function started_line({ handoff, built }: Started): string {
+	const { provider, model, effort } = built.profile
+
+	return `run:handoff: \`${handoff.line}\` → ${provider} ${model} / ${effort} (${built.profile.role})`
+}
+
+function result_lines(log: string): ReadonlyArray<string> {
+	const message = run_handoff_final.final_message(log)
+
+	if (message === undefined) return ['final message: none — read the log']
+
+	const urls = run_handoff_final.github_urls(message)
+
+	return ['final message:', message, ...urls.map((url) => `created: ${url}`)]
+}
+
+// The retrospective unit succeeded only if its `run:carry --retrospective` mark is on the record; its own
+// exit code cannot say so, since a session that never wrote the mark still ends cleanly.
+function closed_retrospective(started: Started, ports: HandoffPorts): number {
+	if (ports.is_retrospective_done(started.git_directory)) return SUCCESS_EXIT_CODE
+
+	return refuse('the retrospective unit ended without run:carry --retrospective', ports)
+}
+
+function waited_exit(started: Started, exit_code: number | null, ports: HandoffPorts): number {
+	if (started.handoff.keyword === run_handoff_args.RETROSPECTIVE_KEYWORD) {
+		return closed_retrospective(started, ports)
+	}
+
+	return exit_code === SUCCESS_EXIT_CODE ? SUCCESS_EXIT_CODE : FAILURE_EXIT_CODE
+}
+
+async function waited(started: Started, ports: HandoffPorts): Promise<number> {
+	const result = await ports.launch_attached(started.request)
+
+	if (result.kind === 'failed') return refuse(`could not start: ${result.note}`, ports)
+
+	const lines = result_lines(ports.read_text(started.log) ?? '')
+
+	for (const line of lines) ports.write(line)
+
+	ports.write(`exit: ${String(result.exit_code)}`)
+
+	return waited_exit(started, result.exit_code, ports)
+}
+
+// The issue the child's `run:entry` claims under: the line's first `#N`, else an unnumbered run.
+function claimant_of(line: string): string {
+	const issue = ISSUE_TOKEN.exec(line)?.[1]
+
+	return issue ?? run_hold.UNNUMBERED_ISSUE
+}
+
+// The detached child's `run:entry` claims this tree and stops on `busy` where only its log would say so,
+// so the claim it would make is asked before the child starts, where the session still reads the answer.
+// A hand-off still starting has not claimed yet and reads free here; `run:entry` stays the guard.
+async function hold_note(started: Started, ports: HandoffPorts): Promise<string | undefined> {
+	const claimant = claimant_of(started.handoff.line)
+
+	return await run_hold_block.blocking_message(await ports.tree_hold(), claimant)
+}
+
+function detached(started: Started, ports: HandoffPorts): number {
+	const result = ports.launch(started.request)
+
+	if (result.kind === 'failed') return refuse(`could not start: ${result.note}`, ports)
+
+	ports.write(`started (pid ${String(result.pid)}); check it with: pnpm josh run:progress --once`)
+
+	return SUCCESS_EXIT_CODE
+}
+
+async function launched(started: Started, ports: HandoffPorts): Promise<number> {
+	const is_waited = run_handoff_launch.is_waited(started.handoff.keyword)
+	const note = is_waited ? undefined : await hold_note(started, ports)
+
+	if (note !== undefined) return refuse(note, ports)
+
+	ports.write(started_line(started))
+	ports.write(`log: ${started.log}`)
+
+	return is_waited ? await waited(started, ports) : detached(started, ports)
+}
+
+function started_of(input: StartInput, ports: HandoffPorts): StartResult {
+	const { handoff, provider, brief, git_directory } = input
+	const prompt = run_handoff_launch.prompt_of(handoff, brief)
+	const role = run_handoff_launch.role_of(handoff.keyword)
+	const child = { prompt, role, provider, cwd: ports.cwd }
+	const built = run_handoff_launch.argv_of(child, ports.environment)
+
+	if (built.kind === 'rejected') return { kind: 'refused', note: `could not start: ${built.note}` }
+
+	const log = run_handoff_launch.log_path(git_directory, handoff.keyword, ports.now())
+	const request = run_handoff_launch.request_of(built, ports.cwd, log)
+
+	return { kind: 'started', started: { handoff, built, request, log, git_directory } }
+}
+
+// A brief file is read as written; none means the generated retrospective brief, whose close names
+// this session — the backlogrun parent that owns the carry — as the mark's owner.
+function brief_of(
+	brief_file: string | undefined,
+	ports: HandoffPorts,
+): { text: string } | { problem: string } {
+	if (brief_file === undefined) {
+		const owner = agent_session_environment.own_session_pid(ports.environment)
+
+		return { text: run_handoff_retrospective.brief(owner) }
+	}
+
+	const read = cli_body.read_result(brief_file)
+
+	return 'problem' in read ? { problem: `could not read ${brief_file}: ${read.problem}` } : read
+}
+
+// A mark already on the record would read as the unit's own close after it ends, so a retrospective
+// no longer owed is refused before any unit starts.
+function is_already_closed(
+	handoff: WorkflowHandoff,
+	git_directory: string,
+	ports: HandoffPorts,
+): boolean {
+	if (handoff.keyword !== run_handoff_args.RETROSPECTIVE_KEYWORD) return false
+
+	return ports.is_retrospective_done(git_directory)
+}
+
+async function handed(
+	handoff: WorkflowHandoff,
+	provider: AgentProvider,
+	ports: HandoffPorts,
+): Promise<number> {
+	const read = brief_of(handoff.brief_file, ports)
+
+	if ('problem' in read) return refuse(read.problem, ports)
+
+	const brief = read.text
+
+	const git_directory = await ports.repository_directory()
+
+	if (git_directory === undefined) return refuse('not inside a git repository', ports)
+
+	if (is_already_closed(handoff, git_directory, ports)) {
+		return refuse('the carry already marks the retrospective as run; nothing is owed', ports)
+	}
+
+	const result = started_of({ handoff, provider, brief, git_directory }, ports)
+
+	return result.kind === 'refused'
+		? refuse(result.note, ports)
+		: await launched(result.started, ports)
+}
+
+async function dispatch(argv: ReadonlyArray<string>, ports: HandoffPorts): Promise<number> {
+	const parsed = run_handoff_args.parse(argv)
+
+	if (parsed.kind === 'refused') return refuse(`${parsed.note}\n${USAGE}`, ports)
+
+	const selected = agent_provider.resolve_provider(ports.environment)
+
+	if (selected.kind === 'rejected') return refuse(selected.note, ports)
+
+	if (parsed.kind === 'backlogrun') {
+		return await ports.backlogrun(with_agent(parsed.rest, selected.provider))
+	}
+
+	return await handed(parsed, selected.provider, ports)
+}
+
+async function run(argv: ReadonlyArray<string>, ports: HandoffPorts = LIVE_PORTS): Promise<number> {
+	if (lane_child_marker.is_child_of(ports.cwd, ports.environment)) {
+		return refuse(
+			'lane children cannot use run:handoff; continue the workflow in this session',
+			ports,
+		)
+	}
+
+	return await dispatch(argv, ports)
+}
+
+const run_handoff_cli = { run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	process.exitCode = await run(process.argv.slice(ARGV_OFFSET))
+}
+
+export type { HandoffPorts }
+export { run_handoff_cli }

package/scripts/run/handoff/run-handoff-final.ts

@@ -0,0 +1,38 @@
+import { json_value } from '#scripts/lib/json-value'
+import { z } from 'zod'
+
+// What a handed-off child said last, read back from its log: a Claude child's `result` event, a Codex
+// child's last completed `agent_message`. The log is the child's stream, one JSON event per line, under
+// the launcher's own header lines, which are not JSON and are passed over.
+
+const CLAUDE_RESULT_SCHEMA = z.object({ type: z.literal('result'), result: z.string() })
+const CODEX_MESSAGE_SCHEMA = z.object({
+	type: z.literal('item.completed'),
+	item: z.object({ type: z.literal('agent_message'), text: z.string() }),
+})
+// An Issue or a pull request, the two things a workflow creates and the brief asks the child to name.
+const GITHUB_URL_PATTERN = /https:\/\/github\.com\/[\w.-]+\/[\w.-]+\/(?:issues|pull)\/\d+/gu
+
+function message_of(line: string): string | undefined {
+	const value = json_value.parse_or_undefined(line)
+
+	return (
+		CLAUDE_RESULT_SCHEMA.safeParse(value).data?.result ??
+		CODEX_MESSAGE_SCHEMA.safeParse(value).data?.item.text
+	)
+}
+
+function final_message(log: string): string | undefined {
+	return log
+		.split('\n')
+		.map((line) => message_of(line))
+		.findLast((message) => message !== undefined)
+}
+
+function github_urls(text: string): ReadonlyArray<string> {
+	return [...new Set(text.match(GITHUB_URL_PATTERN))]
+}
+
+const run_handoff_final = { final_message, github_urls }
+
+export { run_handoff_final }

package/scripts/run/handoff/run-handoff-launch.ts

@@ -0,0 +1,113 @@
+import { agent_argv, type AgentArgvResult } from '#scripts/agent/agent-argv'
+import {
+	agent_role_profile,
+	type AgentEnvironment,
+	type AgentProvider,
+	type AgentRole,
+} from '#scripts/agent/agent-role-profile'
+import { agent_safe_text } from '#scripts/agent/agent-safe-text'
+import { backlogrun_launch } from '#scripts/backlog/backlogrun-launch'
+import { durable_state } from '#scripts/josh/durable-state'
+import type { LaunchRequest } from '#scripts/run/detached-launch'
+import { run_headless } from '#scripts/run/run-headless'
+import type { WorkflowHandoff, WorkflowKeyword } from './run-handoff-args'
+
+// The child `josh run:handoff` starts: the role its keyword runs as, the prompt, the argv and the log.
+//
+// **The profile is the role's, never the main session's model.** The provider is the main session's own,
+// so a consultation on Claude Code hands to a Claude child and one on Codex to a Codex child; the model
+// and effort come from the role profile, resolved from an environment cleared of the session's keys
+// exactly as `josh backlogrun` resolves its parent's (`backlogrun-launch.ts`).
+//
+// A profile on a consultation model is refused by `agent_role_profile.resolve` itself, as for every
+// launcher: the child would be refused its `run:entry` and pointed back here (joshuafolkken/kit#5616).
+
+type BuiltArgv = Extract<AgentArgvResult, { kind: 'argv' }>
+
+interface HandoffChild {
+	prompt: string
+	role: AgentRole
+	provider: AgentProvider
+	cwd: string
+}
+
+// `kickoff` files and plans, as the scheduler does; the runs that implement are the worker's.
+const ROLES: Readonly<Record<WorkflowKeyword, AgentRole>> = {
+	kickoff: agent_role_profile.SCHEDULER,
+	fullrun: agent_role_profile.WORKER,
+	halfrun: agent_role_profile.WORKER,
+	prrun: agent_role_profile.WORKER,
+	retrospective: agent_role_profile.SCHEDULER,
+}
+
+// Names the child's origin in its opening prompt, which is how `josh cost:audit` tells a handed-over run
+// from a typed one (`cost-audit-kind.ts`); every past wording of the preamble carries it.
+const ORIGIN_MARKER = 'through `josh run:handoff`'
+
+// The child is started headless: no person answers it, so a stop that needs one ends its session, and
+// what it says last is all the session that handed it over reads back.
+const PREAMBLE = [
+	`Handed over by another session ${ORIGIN_MARKER}; the brief below is the work it hands over.`,
+	'Nobody answers this session: a question for the person ends it, written as the final message.',
+	'End the final message with the URL of every Issue and pull request this run created.',
+].join(' ')
+
+function role_of(keyword: WorkflowKeyword): AgentRole {
+	return ROLES[keyword]
+}
+
+// The keyword line comes first, so the child reads it as the explicit invocation it is.
+function prompt_of(handoff: WorkflowHandoff, brief: string): string {
+	return agent_safe_text.printable(`${handoff.line}\n\n${PREAMBLE}\n\n${brief.trim()}`)
+}
+
+function argv_of(
+	child: HandoffChild,
+	environment: AgentEnvironment = process.env,
+): AgentArgvResult {
+	const chosen = backlogrun_launch.chosen_environment(child.provider, environment)
+	const resolved = agent_role_profile.resolve(child.role, chosen)
+
+	if (resolved.kind === 'rejected') return resolved
+
+	return agent_argv.with_profile_in(child.prompt, resolved.profile, child.cwd)
+}
+
+function log_path(git_directory: string, keyword: WorkflowKeyword, now: number): string {
+	const suffix = `-${keyword}-${String(now)}.log`
+
+	return durable_state.path(durable_state.PREFIX.HANDOFF_LOG, git_directory, suffix)
+}
+
+// The child's own `josh` commands resolve the provider it was handed, never a Codex session this was
+// typed in — the same environment `josh backlogrun` hands its parent. It is marked a hand-off child, so
+// a `backlogrun` parent that starts the retrospective unit is never driven or cut by the unit's hooks.
+function request_of(built: BuiltArgv, cwd: string, log: string): LaunchRequest {
+	const environment = {
+		...run_headless.handoff_child_environment(),
+		[agent_role_profile.CODEX_SESSION_KEY]: undefined,
+		[agent_role_profile.HANDED_PROVIDER_KEY]: built.profile.provider,
+	}
+
+	return { argv: built.argv, cwd, env: environment, log_path: log, profile: built.profile }
+}
+
+// `kickoff` ends at a filed Issue or a plan, and `retrospective` at its carry mark, so their result is
+// waited for; a run that implements takes long enough that the main session is handed the log and
+// `run:progress` instead.
+function is_waited(keyword: WorkflowKeyword): boolean {
+	return keyword === 'kickoff' || keyword === 'retrospective'
+}
+
+const run_handoff_launch = {
+	ORIGIN_MARKER,
+	argv_of,
+	is_waited,
+	log_path,
+	prompt_of,
+	request_of,
+	role_of,
+}
+
+export type { BuiltArgv, HandoffChild }
+export { run_handoff_launch }

package/scripts/run/handoff/run-handoff-retrospective.ts

@@ -0,0 +1,48 @@
+// The brief `josh run:handoff retrospective` hands the end-of-run retrospective unit: the procedure
+// `.claude/skills/workflow-commands/retrospective.md` spells out, so the unit, not the backlogrun parent,
+// runs them. Every `issue:file` brake (the origin ceiling, the WIP cap, `--max`, `cost --cut`) and
+// its `auto-ok` judgement still apply, since the unit files through the same command.
+//
+// The unit's exit is not its own word: `run:handoff` reads the carry record after it ends and exits 0
+// only when `run:carry --retrospective` marked it (`run-handoff-cli.ts`).
+//
+// The carry belongs to the backlogrun parent, and `run:carry` refuses a mark from any other live
+// session (`run-carry.ts` → `is_count_refused`), so the close names the parent's pid as `--owner`.
+
+const RETROSPECTIVE_DOC = '.claude/skills/workflow-commands/retrospective.md'
+const DIGEST_COMMAND = 'pnpm josh retrospective'
+const FILE_COMMAND = 'pnpm josh issue:file'
+const CLOSE_COMMAND = 'pnpm josh run:carry --retrospective'
+const OWNER_FLAG = '--owner'
+
+// No known parent pid leaves `--owner` out; the record then names no live owner to refuse the mark.
+function close_line(owner: number | undefined): string {
+	const owner_part = owner === undefined ? '' : ` ${OWNER_FLAG} ${String(owner)}`
+
+	return `${CLOSE_COMMAND}${owner_part} --summary "<result>"`
+}
+
+function steps(owner: number | undefined): ReadonlyArray<string> {
+	return [
+		`You are the end-of-run retrospective unit. Read \`${RETROSPECTIVE_DOC}\` in full first; it governs every step below.`,
+		`1. Run \`${DIGEST_COMMAND}\` once.`,
+		`2. Put the top two \`Improvement picks\` through the depth test (\`observation-filing.md\` → "The depth test") and file each that passes with the \`${FILE_COMMAND}\` line the digest prints; its \`auto-ok\` judgement and every brake apply as printed.`,
+		'3. Send the `stack:` lines to the observation ledger.',
+		`4. Close with \`${close_line(owner)}\`, naming the issues filed (or none) and the candidates dropped with why.`,
+		'Ask nobody and file nothing beyond these steps. When step 4 cannot be written, say why as the final message.',
+	]
+}
+
+function brief(owner?: number): string {
+	return steps(owner).join('\n')
+}
+
+const run_handoff_retrospective = {
+	CLOSE_COMMAND,
+	DIGEST_COMMAND,
+	FILE_COMMAND,
+	OWNER_FLAG,
+	brief,
+}
+
+export { run_handoff_retrospective }

package/scripts/run/handoff-lanes/run-handoff-lanes-cli.ts

@@ -0,0 +1,31 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { run_handoff_lanes } from './run-handoff-lanes'
+
+// `josh run:handoff-lanes` — the hand-off chain (`run-handoff-lanes.ts`); it takes no arguments.
+
+const FAILURE_EXIT_CODE = 1
+const ARGV_OFFSET = 2
+const USAGE = 'Usage: josh run:handoff-lanes'
+
+function print(text: string): void {
+	console.info(text)
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	if (argv.length > 0) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	return await run_handoff_lanes.run({ ...run_handoff_lanes.DEFAULT_IO, print })
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	process.exitCode = await run(process.argv.slice(ARGV_OFFSET))
+}
+
+const run_handoff_lanes_cli = { USAGE, run }
+
+export { run_handoff_lanes_cli }