@joshuafolkken/kit 1.872.0

package/scripts/run/detached-launch.ts

@@ -0,0 +1,360 @@
+import { spawn, type SpawnOptions } from 'node:child_process'
+import { closeSync, constants, openSync, writeSync } from 'node:fs'
+import { agent_launch_environment } from '#scripts/agent/agent-launch-environment'
+import { agent_role_profile, type AgentProfile } from '#scripts/agent/agent-role-profile'
+import { agent_session_environment } from '#scripts/josh/agent-session-environment'
+import { stamp_file } from '#scripts/josh/stamp-file'
+
+// Starting a process that outlives this one, and keeping what it writes.
+//
+// **It was `run-wake-session.ts`'s until a second caller needed it** (joshuafolkken/kit#1749). The
+// supervisor was the only thing launching a detached session, so the launcher and the
+// `backlogrun`-specific invocation parsing sat in one file; a delegated child launched into a lane
+// needs exactly the launcher and none of the parsing. Copying it across would be the clone
+// `CLAUDE.md` prohibits — and this is the shape of clone that fails silently, because the copy that
+// drifts is the one that forgets to strip the parent session's environment and dies at its first API
+// request with nothing naming the cause (joshuafolkken/kit#1760).
+//
+// **What is shared is the mechanism, never the argument vector.** Each caller composes its own
+// `LaunchArgv` out of its own constants and validated values — `run-wake-session.ts` rebuilds a
+// `backlogrun` invocation, `lane-dispatch.ts` composes a `fullrun #<N>` out of a digits-only issue
+// number — and this module refuses one that carries anything a command line has no business holding.
+
+const NO_PID_NOTE = 'the process started without a pid'
+const UNSAFE_NOTE =
+	'the wake command or its arguments contain characters that are not safe to execute'
+
+// Provider-specific commands and flags are composed before this boundary. This module accepts only
+// an argv vector and never infers policy from it; role/model/effort arrive separately as log metadata.
+// The provider adapter keeps the fixed binary and permission flags in one reviewed place.
+// **The inputs that reach `spawn` are validated rather than trusted, and that is a control rather than
+// a formality.** Two things already bound this — the argument vector never goes through a shell, so
+// there is no shell to inject into, and the invocation travels as exactly one argv element rather than
+// being interpolated into a command string — but neither is visible at the call site, and "it cannot be
+// exploited the way this is written today" is an argument, not a check. A later edit that added
+// `shell: true` would silently turn both into nothing.
+//
+// A NUL byte is what `execve` treats as the end of a string, so a value carrying one executes as a
+// prefix of itself; the other control characters have no business in a command line and their presence
+// means the value did not come from where it was supposed to.
+//
+// The shared value validation lives with the role policy so environment overrides and argv elements
+// cannot disagree about which control characters or lengths are safe.
+interface LaunchArgv {
+	command: string
+	args: ReadonlyArray<string>
+}
+
+type LaunchResult = { kind: 'launched'; pid: number } | { kind: 'failed'; note: string }
+type AttachedLaunchResult =
+	{ kind: 'completed'; pid: number; exit_code: number | null } | { kind: 'failed'; note: string }
+
+interface LaunchRequest {
+	argv: LaunchArgv
+	cwd: string
+	// Where to keep what the child writes. **Absent means the output is discarded**, which is what every
+	// launch did before joshuafolkken/kit#1746 and what a caller with nowhere to write still gets — the
+	// log is an improvement on the diagnosis, never a precondition for starting a session.
+	log_path?: string | undefined
+	// Extra variables to set on the child, spread **after** the parent-session strip below, so a caller
+	// can hand the child a fact the inherited environment does not carry — a dispatched lane child's mark
+	// among them (joshuafolkken/kit#1904). Setting it here rather than mutating `process.env` keeps the
+	// launcher's own environment untouched, and spreading it last means an explicit value wins over an
+	// inherited one of the same name.
+	env?: Readonly<Record<string, string | undefined>>
+	// Resolved before this provider-independent launcher is called. It is launch metadata, not an
+	// argument source: the provider adapter already placed the same model and effort in `argv`.
+	profile?: AgentProfile | undefined
+}
+
+const { is_safe_value } = agent_role_profile
+
+// The single gate every argument vector passes before it reaches the operating system, whoever
+// composed it.
+function is_safe_argv(argv: LaunchArgv): boolean {
+	return is_safe_value(argv.command) && argv.args.every((value) => is_safe_value(value))
+}
+
+function note_of(error: unknown): string {
+	return error instanceof Error ? error.message : JSON.stringify(error)
+}
+
+function launched(pid: number): LaunchResult {
+	return { kind: 'launched', pid }
+}
+
+// **Appended to without following a symlink, and refused unless the file is this account's own.** The
+// path is deterministic — the temp directory plus a digest of the repository — so on a shared `/tmp`
+// anyone who knows the checkout can work it out and pre-create it. `O_NOFOLLOW` is what stops the
+// append landing wherever a symlink pointed, and the ownership test is the second half, against a
+// plain file another account left at the same path. It is `stamp_file`'s own test rather than a second
+// copy of one, and together the two give this file the defense `write_exclusively` already gives the
+// wake and carry records beside it.
+//
+// `LOG_MODE` applies on creation alone, which is why the ownership test is not redundant: a file this
+// account already owns is trusted whatever mode it carries, and one it does not is refused outright.
+// eslint-disable-next-line no-bitwise -- POSIX open flags are a bit field; `||` here would be a bug
+const LOG_FLAGS = constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW
+const LOG_MODE = 0o600
+
+function profile_suffix(profile: AgentProfile | undefined): string {
+	return profile === undefined ? '' : ` · ${agent_role_profile.describe(profile)}`
+}
+
+// One line in front of each launch, so the sessions started into one file can be told apart. The
+// child's own pid is not known until `spawn` returns, and a header written afterwards would race the
+// child's first output; the time and the launching process separate the runs.
+function log_header(argv: LaunchArgv, profile?: AgentProfile): string {
+	const stamp = new Date().toISOString()
+
+	return `\n=== ${stamp} · started by process ${String(process.pid)} · ${argv.command}${profile_suffix(profile)} ===\n`
+}
+
+function opened_log(log_path: string, on_error: (note: string) => void): number | undefined {
+	const descriptor = openSync(log_path, LOG_FLAGS, LOG_MODE)
+
+	if (!stamp_file.is_own_regular_file(log_path)) {
+		closeSync(descriptor)
+		// Worded for both callers: `ensure_log` reaches this from `--list` and `--stop`, where nothing
+		// has been launched and "the session output is discarded" would describe an event that did not
+		// happen. What holds on every path is that nothing is kept there.
+		on_error(`${log_path} is not this account's own file, so nothing is kept there`)
+
+		return undefined
+	}
+
+	return descriptor
+}
+
+// **The header is written by the launch and by nothing else.** Opening the file and announcing a
+// launch into it were one function until joshuafolkken/kit#1759, which is what made the file's
+// existence a side effect of launching: there was no way to obtain the descriptor without also
+// claiming a session had started. Split, `ensure_log` below can create the file the moment its path
+// is named, and a log nothing has launched into stays empty rather than carrying a header for a
+// session that never ran.
+//
+// **It swallows its own failure, because a log failure is never a failed launch.** In `opened_log`
+// this write sat inside `open_log`'s `try`, so a full disk lost the header and started the session
+// anyway; reached from `launch`'s `try` it would answer `failed` instead and leave a cut
+// `backlogrun` asleep — the one outcome `open_log`'s comment below rules out.
+function stamped(
+	descriptor: number | undefined,
+	argv: LaunchArgv,
+	profile: AgentProfile | undefined,
+	on_error: (note: string) => void,
+): void {
+	if (descriptor === undefined) return
+
+	try {
+		writeSync(descriptor, log_header(argv, profile))
+	} catch (error) {
+		on_error(`the session log could not be written: ${note_of(error)}`)
+	}
+}
+
+// **Opening the log is allowed to fail, and a failure is not a failed launch.** A temp directory that
+// cannot be written to is a reason to lose the diagnosis, never a reason to leave the run asleep — so
+// this answers `undefined` and the spawn goes ahead discarding output, exactly as it did before
+// joshuafolkken/kit#1746.
+//
+// **It says so rather than failing quietly, though.** `--list` and every warning name this path
+// unconditionally, so a silent failure would send a person at three in the morning to a file holding
+// nothing of this run — the silent diagnosis joshuafolkken/kit#1746 was filed about, arrived at from
+// the other side.
+function open_log(
+	log_path: string | undefined,
+	on_error: (note: string) => void,
+): number | undefined {
+	if (log_path === undefined) return undefined
+
+	try {
+		return opened_log(log_path, on_error)
+	} catch (error) {
+		on_error(`the session log at ${log_path} could not be opened: ${note_of(error)}`)
+
+		return undefined
+	}
+}
+
+// **The file exists because its path was resolved, not because something launched into it**
+// (joshuafolkken/kit#1759). `--list`, the already-running branch of `--start` and every warning name
+// this path unconditionally, and until this existed none of the three created anything: the file was
+// written only by the process that launched, at the moment it launched. So a supervisor started
+// before the log existed — detached, and alive for the hours a `backlogrun` takes — left the path
+// named for the whole run with nothing ever at it, and the one report a failure could make went to
+// that same absent file. Creating it where it is named is what makes the name a promise the reader
+// can check: an empty log says "this supervisor started nothing", which is an answer, where a
+// missing one said nothing at all.
+//
+// **No header is written here**, because nothing has been launched — see `stamped` above.
+function ensure_log(log_path: string, on_error: (note: string) => void): void {
+	const descriptor = open_log(log_path, on_error)
+
+	if (descriptor !== undefined) closeSync(descriptor)
+}
+
+// **`detached` is what puts the child outside the conversation, and discarding its output was never
+// part of that** (joshuafolkken/kit#1746). A process left attached is a child of the agent session,
+// and the session cut is exactly the moment this has to survive — so a supervisor that the harness
+// backgrounds, the way `run:progress` is backgrounded, would die at the one event it exists to handle.
+// That argument is about the parent link alone. `stdio: 'ignore'` rode along with it and threw away
+// the one record that could say why a woken session exited without claiming the carry record, which is
+// the whole of what joshuafolkken/kit#1746 could not diagnose. Pointed at a file, the child is just as
+// detached and the output survives it.
+//
+// **The parent session's environment is removed here, and that is why it is here rather than at each
+// call site** (joshuafolkken/kit#1760). A detached child outlives the invocation that spawned it, so a
+// loopback proxy exported into that invocation is a dead address by the time the child dials it —
+// `ConnectionRefused` at the first API request, with nothing anywhere naming the cause. A second
+// launcher that composed its own `SpawnOptions` would be one edit away from that failure.
+//
+// The `error` listener is not decoration: an unhandled `error` on a child process throws in this
+// process, and an agent CLI that is not on `PATH` raises one asynchronously, after `spawn` has
+// already returned. It reports rather than decides — the grace window in `run-wake.ts` is what turns a failed
+// launch into a verdict, so that one detector covers a missing binary, a session that dies during boot
+// and a session that runs without ever picking the run up.
+// Lifted out of the call so the `spawn` fits on one line, which is where the suppression below has to
+// sit: SonarQube's marker applies to the line the issue is raised on and to nothing else.
+function spawn_options(
+	cwd: string,
+	log: number | undefined,
+	environment: Readonly<Record<string, string | undefined>> = {},
+	is_detached = true,
+): SpawnOptions {
+	return {
+		cwd,
+		detached: is_detached,
+		stdio: log === undefined ? 'ignore' : ['ignore', log, log],
+		env: { ...process.env, ...agent_session_environment.removed_environment(), ...environment },
+	}
+}
+
+function notify_spawn(
+	pid: number | undefined,
+	on_spawn: (pid: number) => void,
+	on_error: (note: string) => void,
+): void {
+	if (pid === undefined) return
+
+	try {
+		on_spawn(pid)
+	} catch (error) {
+		on_error(`the child state could not be recorded: ${note_of(error)}`)
+	}
+}
+
+async function attached_spawn(
+	request: LaunchRequest,
+	log: number | undefined,
+	on_error: (note: string) => void,
+	on_spawn: (pid: number) => void,
+): Promise<AttachedLaunchResult> {
+	return await new Promise((resolve) => {
+		const environment = agent_launch_environment.build(request.cwd, request.profile, request.env)
+		const child = spawn(
+			request.argv.command,
+			[...request.argv.args],
+			spawn_options(request.cwd, log, environment, false),
+		) // NOSONAR — shell stays false
+
+		child.once('error', (error) => {
+			on_error(note_of(error))
+			resolve({ kind: 'failed', note: note_of(error) })
+		})
+		child.once('exit', (exit_code) => {
+			resolve({ kind: 'completed', pid: child.pid ?? 0, exit_code })
+		})
+		notify_spawn(child.pid, on_spawn, on_error)
+	})
+}
+
+function ignore_spawn(_pid: number): void {
+	/* caller does not need the attached child's pid */
+}
+
+// **`tssecurity:S8705` is suppressed on the `spawn` line, and this is the reason it is allowed to be.**
+// The rule's premise is a shell escape — it fires where untrusted text can become shell syntax. There
+// is no shell on this path to escape from: `spawn` is handed a command and an argument **array**,
+// `shell` is left at its default of false, so nothing here is ever parsed by `sh`. And every element of
+// that array is a constant or an integer the caller composed, because each caller takes the text it was
+// handed apart and rebuilds it rather than passing it on.
+//
+// **It is what was left after the flow was actually broken, not something used instead of breaking
+// it.** Three earlier rounds tried to satisfy the rule by inspecting the string harder and moved it not
+// at all; the rebuild is what severed the flow, and the same change retired the pattern CodeQL had
+// found an exponential backtrack in — **`js/redos` is gone from this file rather than suppressed, and
+// this marker covers nothing of it.** What the rule still sees is the shape of a `spawn` reached from a
+// file that was read, and that shape is the design: starting a process from a record is the whole of
+// what a supervisor does.
+//
+// Scoped to that one line on the user's explicit instruction of 2026-09-10 (joshuafolkken/kit#1719).
+// No project-wide exclusion and no change to the Sonar configuration.
+function spawned(
+	request: LaunchRequest,
+	log: number | undefined,
+	on_error: (note: string) => void,
+): LaunchResult {
+	const { command, args } = request.argv
+	const environment = agent_launch_environment.build(request.cwd, request.profile, request.env)
+	const child = spawn(command, [...args], spawn_options(request.cwd, log, environment)) // NOSONAR — see above
+
+	child.on('error', (error) => {
+		on_error(note_of(error))
+	})
+	child.unref()
+
+	return child.pid === undefined ? { kind: 'failed', note: NO_PID_NOTE } : launched(child.pid)
+}
+
+// **The descriptor is closed as soon as the spawn returns, and that loses nothing.** `spawn` forks and
+// execs before it returns, so the child already holds its own duplicate of the descriptor by then;
+// what is closed here is this process's copy. Left open it would outlive the launch in a supervisor
+// that runs for hours and launches once per cut.
+function launch(request: LaunchRequest, on_error: (note: string) => void): LaunchResult {
+	if (!is_safe_argv(request.argv)) return { kind: 'failed', note: UNSAFE_NOTE }
+
+	const log = open_log(request.log_path, on_error)
+
+	try {
+		stamped(log, request.argv, request.profile, on_error)
+
+		return spawned(request, log, on_error)
+	} catch (error) {
+		return { kind: 'failed', note: note_of(error) }
+	} finally {
+		if (log !== undefined) closeSync(log)
+	}
+}
+
+async function launch_attached(
+	request: LaunchRequest,
+	on_error: (note: string) => void,
+	on_spawn: (pid: number) => void = ignore_spawn,
+): Promise<AttachedLaunchResult> {
+	if (!is_safe_argv(request.argv)) return { kind: 'failed', note: UNSAFE_NOTE }
+	const log = open_log(request.log_path, on_error)
+
+	try {
+		stamped(log, request.argv, request.profile, on_error)
+
+		return await attached_spawn(request, log, on_error, on_spawn)
+	} catch (error) {
+		return { kind: 'failed', note: note_of(error) }
+	} finally {
+		if (log !== undefined) closeSync(log)
+	}
+}
+
+const detached_launch = {
+	UNSAFE_NOTE,
+	ensure_log,
+	is_safe_argv,
+	is_safe_value,
+	launch,
+	launch_attached,
+	log_header,
+	note_of,
+}
+
+export type { LaunchArgv, LaunchRequest, LaunchResult }
+export { detached_launch }

package/scripts/run/run-carry-args.ts

@@ -0,0 +1,264 @@
+import { parseArgs } from 'node:util'
+import { run_carry, type CarryChange, type CarryClaimRequest, type CarryOwner } from './run-carry'
+import { run_issue_number } from './run-issue-number'
+
+// The argument half of `josh run:carry`. It sat inside `run-carry-cli.ts` until the ownership answers
+// joshuafolkken/kit#1722 added took that file to 96% of the 300-line limit, and the seam it split on
+// was already there: everything here turns `argv` into one `Request` and reads no record, while
+// everything left there acts on a record and prints. Nothing about the behavior moved with it.
+
+const NO_INCREMENT = 0
+const ONE_CUT = 1
+// The four request groups below are mutually exclusive, so more than one of them named in a single
+// invocation is a usage error rather than an order to guess.
+const ONE_GROUP = 1
+const COUNT_PATTERN = /^\d+$/u
+const EMPTY_INVOCATION = ''
+// A pid below this addresses a process group rather than a process, which `process-identity.ts`
+// rejects on the read side. Refused here too, so a record never records an owner nothing can be.
+const MIN_PID = 1
+// `--owner` is read by the two claiming alternatives and by the counting group (joshuafolkken/kit#1935):
+// a count checks the owner so a session whose record was handed off, or taken over by a successor,
+// cannot advance a budget that is no longer its own. `--end` alone accepts it and ignores it, and a
+// usage line that offered it there would be promising an ownership check nothing performs.
+const USAGE =
+	'Usage: josh run:carry [--json] | --begin <invocation> [--owner <pid>] | --resume <invocation> [--owner <pid>] | (--cut | --merged <count> | --filed <count> | --done <issue> | --retrospective --summary <text>) [--owner <pid>] | --end [--stopped <reason>]'
+
+const OPTIONS = {
+	begin: { type: 'string' },
+	cut: { type: 'boolean' },
+	done: { type: 'string' },
+	end: { type: 'boolean' },
+	filed: { type: 'string' },
+	json: { type: 'boolean' },
+	merged: { type: 'string' },
+	owner: { type: 'string' },
+	// A boolean like `--cut`: it marks the end-of-run retrospective as run rather than counting an
+	// amount (joshuafolkken/kit#2328). It joins the counting group, so it carries `--owner` and is
+	// refused from a session that no longer owns the record, exactly as a merge count is.
+	retrospective: { type: 'boolean' },
+	resume: { type: 'string' },
+	// The retrospective's result carried to the event stream (joshuafolkken/kit#2342). It pairs with
+	// `--retrospective` and only with it: the mark and the result it records are one action, so a mark
+	// with nothing to read and a result no mark records are both usage errors rather than half-done
+	// closes. It is not a record field — `to_change` never carries it — so it rides the count request to
+	// the emit side alone.
+	summary: { type: 'string' },
+	// **`--stopped <reason>` rides on `--end`, so it is a modifier rather than a fifth group.** A run
+	// that halts needing a person ends its record exactly as a clean one does; the reason is what turns
+	// that end into the ⏸️ confirmation the person gets after a session cut (joshuafolkken/kit#2136).
+	// Named without `--end` it is ignored, the way a read ignores every counting flag.
+	stopped: { type: 'string' },
+} as const
+
+type OptionName = keyof typeof OPTIONS
+type ParsedValues = Partial<Record<OptionName, string | boolean>>
+// What `parseArgs` hands back for one option: the flag's own type, or nothing where it was not named.
+type OptionValue = string | boolean | undefined
+
+// The counting request carries the owner so `count` can refuse a write from a session that is no
+// longer the record's owner (joshuafolkken/kit#1935).
+interface CountRequest {
+	kind: 'count'
+	change: CarryChange
+	owner: CarryOwner
+	// The retrospective result to emit, present exactly when `change.retrospective` is set and never
+	// otherwise (joshuafolkken/kit#2342). The CLI reads it to append one event as it applies the mark.
+	summary?: string
+}
+
+type Request =
+	| CountRequest
+	| { kind: 'read' }
+	| { kind: 'claim'; claim: CarryClaimRequest }
+	| { kind: 'end'; stopped: string | undefined }
+
+const READ_REQUEST: Request = { kind: 'read' }
+
+function read_arguments(argv: ReadonlyArray<string>): ParsedValues | undefined {
+	try {
+		return parseArgs({ args: [...argv], options: OPTIONS, strict: true }).values
+	} catch {
+		return undefined
+	}
+}
+
+function text_of(value: OptionValue): string | undefined {
+	return typeof value === 'string' ? value : undefined
+}
+
+// Absent is zero; present but not a count is `undefined`, which invalidates the whole invocation
+// rather than quietly counting nothing.
+function to_count(value: OptionValue): number | undefined {
+	const text = text_of(value)
+
+	if (text === undefined) return NO_INCREMENT
+
+	return COUNT_PATTERN.test(text) ? Number(text) : undefined
+}
+
+// **`--done` names an issue, so it is checked as one and not as a count.** The shape is
+// `run-issue-number.ts`'s, which already refuses `0` and a leading zero — the same rule the `run:*`
+// commands interpolate a number under, imported rather than restated. Absent is an empty object rather
+// than a zero: there is no issue to record, which is a different fact from recording issue zero. A
+// present-but-malformed value invalidates the whole invocation, exactly as a bad `--merged` does.
+function to_done(value: OptionValue): Pick<CarryChange, 'done'> | undefined {
+	const text = text_of(value)
+
+	if (text === undefined) return {}
+
+	if (!run_issue_number.ISSUE_NUMBER_PATTERN.test(text)) return undefined
+
+	const issue = Number(text)
+
+	// The pattern is anchored on digits and bounds nothing, so the magnitude check is separate — the
+	// same shape `backlog_budget_cli.to_count` ends with. A number past the safe range would be
+	// recorded as a different number and never match anything in `remaining`.
+	return Number.isSafeInteger(issue) ? { done: issue } : undefined
+}
+
+// The two boolean marks in the counting group — `--cut` and `--retrospective` — as the partial the
+// change spreads. Kept apart from `to_change` so its own decision count stays under the limit.
+function to_marks(values: ParsedValues): Pick<CarryChange, 'cuts' | 'retrospective'> {
+	const cuts = values.cut === true ? ONE_CUT : NO_INCREMENT
+	const retrospective = values.retrospective === true ? { retrospective: true } : {}
+
+	return { cuts, ...retrospective }
+}
+
+function to_change(values: ParsedValues): CarryChange | undefined {
+	const merged = to_count(values.merged)
+	const filed = to_count(values.filed)
+	const done = to_done(values.done)
+
+	if (merged === undefined || filed === undefined || done === undefined) return undefined
+
+	return { merged, filed, ...to_marks(values), ...done }
+}
+
+// **A counting flag is what makes a count, never the sum of one.** `--merged 0` is a run reporting
+// that a wave merged nothing, and reading it as a bare read would answer `none` with exit 0 against
+// a record that is not there — the silent zero `docs/josh-commands.md` says exits 1.
+function has_count(values: ParsedValues): boolean {
+	return (
+		values.cut === true ||
+		values.retrospective === true ||
+		values.merged !== undefined ||
+		values.filed !== undefined ||
+		values.done !== undefined
+	)
+}
+
+// The four groups are mutually exclusive: `--begin` starts a run, `--resume` adopts one, `--end`
+// finishes one, and the counters change one that is already there. Two groups in one invocation is a
+// usage error, never a guessed order between them.
+function group_count(values: ParsedValues): number {
+	const groups = [
+		values.begin !== undefined,
+		values.resume !== undefined,
+		values.end === true,
+		has_count(values),
+	]
+
+	return groups.filter(Boolean).length
+}
+
+// **`--owner` is what makes liveness answerable at all.** The process that runs this command is a
+// short-lived `tsx`, so its own pid says nothing about whether the run is still going; the caller
+// names the process that is — its own session — and a `backlogrun` passes `--owner "$PPID"`. Absent,
+// the record simply declares no owner and every standing record reads as not provably live, which
+// refuses rather than resumes.
+function to_owner(value: OptionValue): CarryOwner | undefined {
+	const text = text_of(value)
+
+	if (text === undefined) return run_carry.NO_OWNER
+
+	if (!COUNT_PATTERN.test(text)) return undefined
+
+	const pid = Number(text)
+
+	return pid < MIN_PID ? undefined : run_carry.owner_of(pid)
+}
+
+// A non-empty `--summary`, or nothing. An empty string is nothing here, so it reads as absent and the
+// pairing check below refuses it against `--retrospective`.
+function summary_text(values: ParsedValues): string | undefined {
+	const summary = text_of(values.summary)
+
+	return summary === undefined || summary === '' ? undefined : summary
+}
+
+// The mark and its result are one close: `--retrospective` needs a `--summary` to record, and a
+// `--summary` names a result no other flag records (joshuafolkken/kit#2342). Either flag without the
+// other is a usage error, so each must be present exactly when the other is.
+function is_summary_paired(values: ParsedValues): boolean {
+	return (summary_text(values) !== undefined) === (values.retrospective === true)
+}
+
+// The counting group, split out so the shape below stays a flat list of exits. The summary rides along
+// only when it is there — guaranteed paired with `--retrospective` by `is_summary_paired` — so a plain
+// `--merged` count never carries one.
+function to_count_request(values: ParsedValues, owner: CarryOwner): Request | undefined {
+	const change = to_change(values)
+
+	if (change === undefined) return undefined
+
+	const summary = summary_text(values)
+
+	return summary === undefined
+		? { kind: 'count', change, owner }
+		: { kind: 'count', change, owner, summary }
+}
+
+// `--begin ""` is a loop whose invocation variable was unset. A record named by nothing is one every
+// other empty `--begin` then reads as its own, which is the cross-run inheritance `classify_claim`
+// exists to refuse — so it is a usage error rather than a record.
+function to_claim_request(
+	invocation: string,
+	owner: CarryOwner,
+	is_adoption: boolean,
+): Request | undefined {
+	if (invocation === EMPTY_INVOCATION) return undefined
+
+	return { kind: 'claim', claim: { invocation, owner, is_adoption } }
+}
+
+function to_other_request(values: ParsedValues, owner: CarryOwner): Request | undefined {
+	if (values.end === true) return { kind: 'end', stopped: text_of(values.stopped) }
+
+	return has_count(values) ? to_count_request(values, owner) : READ_REQUEST
+}
+
+function to_named_request(values: ParsedValues, owner: CarryOwner): Request | undefined {
+	const begun = text_of(values.begin)
+
+	if (begun !== undefined) return to_claim_request(begun, owner, false)
+
+	const adopted = text_of(values.resume)
+
+	if (adopted !== undefined) return to_claim_request(adopted, owner, true)
+
+	return to_other_request(values, owner)
+}
+
+function to_request(values: ParsedValues): Request | undefined {
+	if (group_count(values) > ONE_GROUP) return undefined
+
+	if (!is_summary_paired(values)) return undefined
+
+	const owner = to_owner(values.owner)
+
+	if (owner === undefined) return undefined
+
+	return to_named_request(values, owner)
+}
+
+const run_carry_args = {
+	OPTIONS,
+	USAGE,
+	read_arguments,
+	to_request,
+}
+
+export type { CountRequest, ParsedValues, Request }
+export { run_carry_args }