@joshuafolkken/kit 1.872.0

package/scripts/adopt/adopt-logic.ts

@@ -0,0 +1,107 @@
+import { repo_discovery } from '#scripts/discovery/repo-discovery'
+import { repo_origin } from '#scripts/discovery/repo-origin'
+import type { Release, ReleasePlan } from '#scripts/propagate/propagate-steps'
+import type { PropagateTarget } from '#scripts/propagate/propagate-targets'
+import { self_sync_guard } from '#scripts/self-sync-guard/self-sync-guard-logic'
+import { KIT_PACKAGE_NAME } from '#scripts/version/kit-descriptor'
+
+// The decisions `josh adopt` makes before any step runs: whether this repository may adopt at all,
+// which repository the issue is opened in, and what the run is carrying (joshuafolkken/kit#1085).
+
+const ADOPT_ORIGIN = 'Opened by `josh adopt` in this repository.'
+const INCOMPLETE_HEADLINE =
+	'Refusing to adopt: these declared toolkits would fall out of the plan, and the run would sync the rest without them.'
+const INCOMPLETE_EFFECT =
+	"The toolkits overlay files derived from kit's own (see docs/sync.md), so syncing kit without one rewrites that overlay back to kit's original — a wrong diff wearing kit's face."
+const MISPLACED_CAUSE =
+	'declared under `dependencies`; the upgrade installs with `pnpm add -D` and would relocate it. Move it to `devDependencies`.'
+const ABSENT_CAUSE =
+	'no runnable CLI here; the package or its `node_modules/.bin` shim is missing. Run `pnpm install`.'
+
+// Adoption never runs inside kit's own repository — the same boundary `josh sync` draws
+// (joshuafolkken/kit#868), and for the same reason: the sync would overwrite the distribution source
+// with its own derived templates. Refused here, before anything writes, rather than left for the
+// sync to fail on halfway through the sequence.
+//
+// It is only kit that is refused, not every repository under the scope. app-kit and game-kit are
+// themselves consumers of kit — `josh propagate` carries kit's releases *into* them — so adopting
+// there is exactly the intended use, and a refusal keyed on the npm scope would lock out the two
+// repositories that need this command most.
+function refuse_inside_kit_repository(project_root: string): string | undefined {
+	if (self_sync_guard.read_package_name(project_root) !== KIT_PACKAGE_NAME) return undefined
+
+	return [
+		`Refusing to adopt: this is ${KIT_PACKAGE_NAME}'s own repository.`,
+		'Adoption carries a published toolkit inward, so it runs in a repository that consumes one.',
+		'Run it from a consumer project instead.',
+	].join('\n')
+}
+
+// The verification gate and the pull request both run through `pnpm josh`, which is kit's own CLI.
+// pnpm writes a `node_modules/.bin` shim only for a project's *direct* dependencies, so a repository
+// that declares app-kit or game-kit alone has no `josh` shim: those two steps would fail *after* the
+// upgrade and the sync had already written, leaving a dirty tree and no pull request. Refused before
+// anything writes instead.
+function refuse_without_kit(releases: ReadonlyArray<Release>): string | undefined {
+	if (releases.some((release) => release.package_name === KIT_PACKAGE_NAME)) return undefined
+
+	return [
+		`Refusing to adopt: ${KIT_PACKAGE_NAME} is not a direct dev dependency here.`,
+		'The verification gate and the pull request run through `pnpm josh`, which it provides.',
+		`Add it with \`pnpm add -D ${KIT_PACKAGE_NAME}\` and run this again.`,
+	].join('\n')
+}
+
+// One indented line per toolkit, so the reader sees which fix belongs to which package rather than
+// two lists to match up by hand.
+function name_causes(package_names: ReadonlyArray<string>, cause: string): Array<string> {
+	return package_names.map((package_name) => `  ${package_name} — ${cause}`)
+}
+
+// A declared toolkit that falls out of the plan is a refusal rather than a warning
+// (joshuafolkken/kit#1540). kit distributes the base files and every other toolkit overlays files
+// *derived* from them (`docs/sync.md` → two distribution tiers), so a run that syncs kit without the
+// overlay does not merely do less — it writes the overlay's paths back to kit's originals. That diff
+// then wears kit's own face in the pull request, which is exactly what a reviewer cannot spot.
+//
+// Warning and continuing was the first round's answer, and it holds only where someone is reading:
+// `josh adopt` runs unattended, and both causes are one command away from fixed — so refusing costs
+// the user a command and continuing costs a wrong diff. Refusing keeps the first round's rule rather
+// than reversing it: the exclusion is still named, and now it also stops.
+function refuse_incomplete_plan(
+	misplaced: ReadonlyArray<string>,
+	unresolved: ReadonlyArray<string>,
+): string | undefined {
+	const moved = name_causes(misplaced, MISPLACED_CAUSE)
+	const named = [...moved, ...name_causes(unresolved, ABSENT_CAUSE)]
+	if (named.length === 0) return undefined
+
+	return [INCOMPLETE_HEADLINE, INCOMPLETE_EFFECT, ...named].join('\n')
+}
+
+// The one target of an adoption: this checkout, named by its own `origin` so the issue and the pull
+// request land in the repository the work is done in. Read from the git config rather than asked of
+// `gh`, which is how the discovery map is built too.
+function resolve_self_target(project_root: string): PropagateTarget | undefined {
+	const origin_url = repo_discovery.read_origin_url(project_root)
+	if (origin_url === undefined) return undefined
+	const identity = repo_origin.parse_origin_url(origin_url)
+	if (identity === undefined) return undefined
+
+	return { repo: repo_origin.format_identity(identity), path: project_root, state: 'ready' }
+}
+
+function build_plan(releases: ReadonlyArray<Release>): ReleasePlan {
+	return { releases, origin: ADOPT_ORIGIN }
+}
+
+const adopt_logic = {
+	ADOPT_ORIGIN,
+	refuse_inside_kit_repository,
+	refuse_without_kit,
+	refuse_incomplete_plan,
+	resolve_self_target,
+	build_plan,
+}
+
+export { adopt_logic }

package/scripts/adopt/adopt-toolkits.ts

@@ -0,0 +1,181 @@
+import path from 'node:path'
+import { find_local_bin_upwards } from '#scripts/build/local-bin'
+import type { Release } from '#scripts/propagate/propagate-steps'
+import { propagate_targets, type Manifest } from '#scripts/propagate/propagate-targets'
+import { KIT_PACKAGE_NAME } from '#scripts/version/kit-descriptor'
+import { z } from 'zod'
+
+// Which `@joshuafolkken/*` toolkits `josh adopt` can upgrade in the repository it is run from
+// (joshuafolkken/kit#1085).
+//
+// Discovery is a filesystem fact rather than a roster written here: a hardcoded list would go stale
+// the day a fourth toolkit is published, and a project that depends on only one of them would be
+// told to sync a CLI it does not have.
+
+const TOOLKIT_SCOPE = '@joshuafolkken/'
+// `josh adopt` pulls whatever is newest inward. The exact-version pin is `josh propagate`'s, and it
+// exists there only because that command waits for a specific publish before carrying it outward.
+const LATEST_VERSION = 'latest'
+const NODE_MODULES = 'node_modules'
+const BASE_RANK = 0
+const DERIVED_RANK = 1
+
+// Only the field the bin name is read from, in both shapes npm accepts. The manifest is read through
+// propagation's own reader, which keeps every other field, so this parses what that reader passed
+// through rather than opening the file a second time (`CLAUDE.md` → "No clones").
+const bin_map_schema = z.record(z.string(), z.string())
+const bin_schema = z.looseObject({ bin: z.union([z.string(), bin_map_schema]).optional() })
+
+function is_toolkit_package(package_name: string): boolean {
+	return package_name.startsWith(TOOLKIT_SCOPE)
+}
+
+// kit is the base tier and every other toolkit distributes files *derived* from kit's, so the two
+// can manage the same path and whichever `sync` ran last decides its contents
+// (`docs/sync.md` → "two distribution tiers"). Ordering is therefore base-first: kit syncs, then the
+// toolkits that overlay it. Sorting by name would put kit last and have it overwrite the overlay
+// with the original every single run.
+function toolkit_rank(package_name: string): number {
+	return package_name === KIT_PACKAGE_NAME ? BASE_RANK : DERIVED_RANK
+}
+
+function compare_toolkits(left: string, right: string): number {
+	const by_rank = toolkit_rank(left) - toolkit_rank(right)
+
+	return by_rank === 0 ? left.localeCompare(right) : by_rank
+}
+
+function scoped_names(declared: Readonly<Record<string, string>> | undefined): Array<string> {
+	return Object.keys(declared ?? {}).filter((package_name) => is_toolkit_package(package_name))
+}
+
+// Toolkits are development tooling, and the shared upgrade builder installs them with `pnpm add -D`
+// (`build_upgrade_shell_command`). A toolkit declared under `dependencies` would therefore be
+// *relocated* into `devDependencies` by the upgrade — a manifest rewrite nobody asked for, riding
+// silently into the pull request. Discovery reads `devDependencies` only for that reason, and
+// `misplaced_toolkits` names what was left out so the omission is reported rather than silent.
+function declared_toolkits(project_root: string): ReadonlyArray<string> {
+	const manifest = propagate_targets.read_manifest(project_root)
+
+	return scoped_names(manifest?.devDependencies).toSorted(compare_toolkits)
+}
+
+// npm accepts two shapes for `bin`. The string form names exactly one executable and its name is the
+// package's *unscoped* one — the rule `read_bin_entry` in `scripts/build/local-bin.ts` reads in the other
+// direction, from a name to a path. The object form is answered by that same unscoped name where it
+// declares one, so a toolkit shipping several CLIs still resolves to one deterministically.
+function pick_bin_name(package_name: string, bin: string | Record<string, string>): string {
+	const unscoped = path.basename(package_name)
+	if (typeof bin === 'string') return unscoped
+	if (bin[unscoped] !== undefined) return unscoped
+
+	return Object.keys(bin)[0] ?? unscoped
+}
+
+function read_installed_manifest(project_root: string, package_name: string): Manifest | undefined {
+	return propagate_targets.read_manifest(path.join(project_root, NODE_MODULES, package_name))
+}
+
+function bin_name_of(package_name: string, installed: Manifest): string | undefined {
+	const parsed = bin_schema.safeParse(installed)
+	const bin = parsed.success ? parsed.data.bin : undefined
+
+	return bin === undefined ? undefined : pick_bin_name(package_name, bin)
+}
+
+// The CLI a toolkit installs, read from the installed package's own `bin` field. Deriving it means
+// `@joshuafolkken/app-kit` answers `josh-app` without anyone maintaining the mapping here.
+function read_bin_name(project_root: string, package_name: string): string | undefined {
+	const installed = read_installed_manifest(project_root, package_name)
+
+	return installed === undefined ? undefined : bin_name_of(package_name, installed)
+}
+
+function has_runnable_cli(project_root: string, bin_name: string): boolean {
+	return find_local_bin_upwards(project_root, bin_name) !== undefined
+}
+
+// A declared toolkit is a target only when its CLI is actually runnable here. A dependency whose
+// shim is missing — an install that never ran, a partial workspace — cannot be told to sync, and
+// spawning it would fail the sync step rather than say what is wrong.
+function resolve_toolkit(project_root: string, package_name: string): Release | undefined {
+	const bin_name = read_bin_name(project_root, package_name)
+	if (bin_name === undefined) return undefined
+	if (!has_runnable_cli(project_root, bin_name)) return undefined
+
+	return { package_name, version: LATEST_VERSION, bin_name }
+}
+
+// Unreachable and not-a-toolkit are two different answers, and collapsing them is what makes a
+// refusal give advice that is wrong. **Unreachable** is a broken install — the package is missing
+// here, or it declares a CLI whose shim is not installed — and `pnpm install` fixes it whatever the
+// package turns out to be. A package that is installed perfectly well and simply ships **no** CLI is
+// a scoped *library* rather than a toolkit: nothing about it is broken, so it is not this, and it is
+// not misplaced either. The `@joshuafolkken/` prefix alone cannot tell the two apart, which is why
+// the question is asked of the installed `bin` field (joshuafolkken/kit#1540 review round 1).
+function is_unreachable_toolkit(project_root: string, package_name: string): boolean {
+	const installed = read_installed_manifest(project_root, package_name)
+	if (installed === undefined) return true
+
+	const bin_name = bin_name_of(package_name, installed)
+
+	return bin_name !== undefined && !has_runnable_cli(project_root, bin_name)
+}
+
+// Only a package that is *demonstrably* a toolkit — installed, with its CLI runnable here — is
+// reported as misplaced. Telling the owner of a scoped runtime library to move it into
+// `devDependencies` would break the build it is there to serve, and one that is not installed at all
+// is answered by `unresolved_toolkits` instead, whose `pnpm install` is the fix that actually
+// applies. Naming only what can be proved is what keeps a refusal honest.
+function misplaced_toolkits(project_root: string): ReadonlyArray<string> {
+	const manifest = propagate_targets.read_manifest(project_root)
+	const development = new Set(scoped_names(manifest?.devDependencies))
+
+	return scoped_names(manifest?.dependencies).filter(
+		(name) => !development.has(name) && resolve_toolkit(project_root, name) !== undefined,
+	)
+}
+
+function discover_toolkits(project_root: string): ReadonlyArray<Release> {
+	return declared_toolkits(project_root)
+		.map((package_name) => resolve_toolkit(project_root, package_name))
+		.filter((release) => release !== undefined)
+}
+
+// Every scoped package this manifest declares, in either field. `unresolved_toolkits` reads both
+// because a broken install is a broken install wherever it was declared, and the fix it reports —
+// `pnpm install` — is right for a package under `dependencies` too.
+function all_declared_toolkits(project_root: string): ReadonlyArray<string> {
+	const manifest = propagate_targets.read_manifest(project_root)
+	const development = scoped_names(manifest?.devDependencies)
+
+	return [...new Set([...development, ...scoped_names(manifest?.dependencies)])]
+}
+
+// The other half of the same read: which declared packages the run cannot reach at all. Dropping
+// them silently is what let a partial install sync kit alone and revert the overlay tier
+// (joshuafolkken/kit#1540), so the caller refuses on this list rather than discovering it as a
+// shorter plan. A scoped library that ships no CLI appears in neither list, because nothing about it
+// is broken.
+function unresolved_toolkits(project_root: string): ReadonlyArray<string> {
+	return all_declared_toolkits(project_root).filter((package_name) =>
+		is_unreachable_toolkit(project_root, package_name),
+	)
+}
+
+const adopt_toolkits = {
+	TOOLKIT_SCOPE,
+	LATEST_VERSION,
+	is_toolkit_package,
+	compare_toolkits,
+	declared_toolkits,
+	misplaced_toolkits,
+	pick_bin_name,
+	read_bin_name,
+	is_unreachable_toolkit,
+	resolve_toolkit,
+	discover_toolkits,
+	unresolved_toolkits,
+}
+
+export { adopt_toolkits }

package/scripts/adopt/adopt.ts

@@ -0,0 +1,171 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { refuse_unknown_flags } from '#scripts/lib/cli-flags'
+import { propagate_run, type TargetResult } from '#scripts/propagate/propagate-run'
+import { propagate_steps, type Release, type ReleasePlan } from '#scripts/propagate/propagate-steps'
+import type { PropagateTarget } from '#scripts/propagate/propagate-targets'
+import { adopt_logic } from './adopt-logic'
+import { adopt_toolkits } from './adopt-toolkits'
+
+// `josh adopt` — upgrade every `@joshuafolkken/*` toolkit installed in this repository to latest,
+// sync each one's managed files, run the verification gate, and open the issue and pull request
+// (joshuafolkken/kit#1085).
+//
+// It is `josh propagate` seen from the other end: propagation stands in the supplier and pushes one
+// released version out to every consumer, adoption stands in the consumer and pulls whatever is
+// newest in. The step sequence is literally the same one — `propagate_run.STEP_ORDER`, run through
+// `propagate_run.run_target` — so the working-tree pre-check, the ordering and the return to the
+// default branch cannot drift between the two.
+//
+// It stops at the open pull request. Merging is what `pnpm josh followup` does, under an
+// authorization a CLI does not have.
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const ARGV_OFFSET = 2
+const DRY_RUN_FLAG = '--dry-run'
+const KNOWN_FLAGS: ReadonlyArray<string> = [DRY_RUN_FLAG]
+const DRY_RUN_REASON = 'would be adopted'
+const NOTHING_TO_ADOPT = 'No @joshuafolkken toolkit is installed here; nothing to adopt.'
+const NO_ORIGIN =
+	'Refusing to adopt: this checkout has no GitHub `origin`, so there is nowhere to open the issue.'
+
+interface RunOptions {
+	is_dry_run: boolean
+	// The usage message, when the arguments were not accepted. Carried alongside rather than returned
+	// instead, so the caller has one shape to branch on.
+	usage?: string
+}
+
+function parse_options(argv: ReadonlyArray<string>): RunOptions {
+	const options: RunOptions = { is_dry_run: argv.includes(DRY_RUN_FLAG) }
+	const usage = refuse_unknown_flags(argv, KNOWN_FLAGS, 'adopt')
+
+	return usage === undefined ? options : { ...options, usage }
+}
+
+function announce_releases(releases: ReadonlyArray<Release>): void {
+	console.info(`Adopting: ${releases.map((release) => release.package_name).join(', ')}`)
+}
+
+function report(result: TargetResult): number {
+	console.info('')
+	console.info(propagate_run.format_report([result]))
+
+	return propagate_run.has_failure([result]) ? FAILURE_EXIT_CODE : SUCCESS_EXIT_CODE
+}
+
+// A dry run describes each step and touches nothing; a real run carries the plan. Both go through
+// the same sequence, so what the dry run lists is what the real run does.
+function run_sequence(target: PropagateTarget, plan: ReleasePlan | undefined): number {
+	const step =
+		plan === undefined ? propagate_steps.describe_step : propagate_steps.create_step_runner(plan)
+	const reason = plan === undefined ? DRY_RUN_REASON : propagate_run.PROPAGATED_REASON
+
+	return report(propagate_run.run_target(target, step, reason))
+}
+
+// A declared toolkit that cannot be carried stops the run, whichever of the two ways it fell out —
+// placed under `dependencies`, or declared with no runnable CLI here (joshuafolkken/kit#1540). The
+// refusal names each one and its cause, so the exclusion is still reported as it was before; what
+// changed is that it no longer leaves the run to sync kit alone and revert the overlay tier.
+//
+// It runs ahead of discovery, so a dry run refuses too: what the dry run lists has to be what the
+// real run does, and a plan it printed here would be a plan nothing will ever execute.
+function refuse_incomplete_plan(project_root: string): number | undefined {
+	const refusal = adopt_logic.refuse_incomplete_plan(
+		adopt_toolkits.misplaced_toolkits(project_root),
+		adopt_toolkits.unresolved_toolkits(project_root),
+	)
+	if (refusal === undefined) return undefined
+
+	console.error(refusal)
+
+	return FAILURE_EXIT_CODE
+}
+
+// Nothing installed is a skip; kit missing is a refusal. Both stop the run before anything writes,
+// and they differ only in the exit code they stop with.
+function stop_reason(releases: ReadonlyArray<Release>): number | undefined {
+	if (releases.length === 0) {
+		console.info(NOTHING_TO_ADOPT)
+
+		return SUCCESS_EXIT_CODE
+	}
+
+	const refusal = adopt_logic.refuse_without_kit(releases)
+	if (refusal === undefined) return undefined
+
+	console.error(refusal)
+
+	return FAILURE_EXIT_CODE
+}
+
+function adopt_target(
+	project_root: string,
+	releases: ReadonlyArray<Release>,
+	is_dry_run: boolean,
+): number {
+	const target = adopt_logic.resolve_self_target(project_root)
+
+	if (target === undefined) {
+		console.error(NO_ORIGIN)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	announce_releases(releases)
+
+	return run_sequence(target, is_dry_run ? undefined : adopt_logic.build_plan(releases))
+}
+
+// The run once the repository has been accepted as a place to adopt into.
+function run_here(project_root: string, is_dry_run: boolean): number {
+	const incomplete = refuse_incomplete_plan(project_root)
+	if (incomplete !== undefined) return incomplete
+
+	const releases = adopt_toolkits.discover_toolkits(project_root)
+	const stop = stop_reason(releases)
+
+	return stop ?? adopt_target(project_root, releases, is_dry_run)
+}
+
+function run(argv: ReadonlyArray<string>, project_root: string = PROJECT_ROOT): number {
+	const options = parse_options(argv)
+
+	if (options.usage !== undefined) {
+		console.error(options.usage)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const refusal = adopt_logic.refuse_inside_kit_repository(project_root)
+
+	if (refusal !== undefined) {
+		console.error(refusal)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	return run_here(project_root, options.is_dry_run)
+}
+
+function main(argv: ReadonlyArray<string>): void {
+	process.exit(run(argv))
+}
+
+const adopt = {
+	DRY_RUN_REASON,
+	KNOWN_FLAGS,
+	NOTHING_TO_ADOPT,
+	parse_options,
+	run_here,
+	run,
+	main,
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) main(process.argv.slice(ARGV_OFFSET))
+
+export type { RunOptions }
+export { adopt }

package/scripts/agent/agent-argv.ts

@@ -0,0 +1,140 @@
+import { agent_diagnostics } from './agent-diagnostics'
+import {
+	agent_role_profile,
+	type AgentEnvironment,
+	type AgentProfile,
+	type AgentRole,
+} from './agent-role-profile'
+import { claude_agent_argv } from './claude-agent-argv'
+import { codex_agent_argv } from './codex-agent-argv'
+
+interface AgentArgv {
+	command: string
+	args: ReadonlyArray<string>
+}
+
+type AgentArgvResult =
+	{ kind: 'argv'; argv: AgentArgv; profile: AgentProfile } | { kind: 'rejected'; note: string }
+
+// **`session_id` forces the fresh session's id, and only the Claude path can honour it**
+// (joshuafolkken/kit#2407). Codex has no such flag, and the run-state report reads Claude transcripts
+// alone, so an OpenAI scheduler simply builds as before; whiff attribution is a Claude-transcript
+// property, so nothing is lost by the omission.
+function build(
+	invocation: string,
+	profile: AgentProfile,
+	cwd?: string,
+	session_id?: string,
+): AgentArgv {
+	return profile.provider === 'openai'
+		? codex_agent_argv.build(invocation, profile, cwd)
+		: claude_agent_argv.build(invocation, profile, session_id, cwd)
+}
+
+// The resume counterpart of `build` (joshuafolkken/kit#2317). Only the Claude path resumes by session
+// id; an OpenAI lane carries no such id at the outage re-dispatch, so it falls back to a fresh build —
+// which is never reached in practice, because `lane-resume.ts` only plans a resume for an Anthropic
+// provider. The fallback keeps this total rather than throwing on a provider it was not handed.
+function build_resume(
+	invocation: string,
+	profile: AgentProfile,
+	session_id: string,
+	cwd?: string,
+): AgentArgv {
+	return profile.provider === 'openai'
+		? codex_agent_argv.build(invocation, profile, cwd)
+		: claude_agent_argv.build_resume(invocation, profile, session_id, cwd)
+}
+
+// **`session_id` threads to the Claude build, so a wake launched in a lane's work tree still forces
+// its transcript id** (joshuafolkken/kit#2407). It is optional, so every other caller of the
+// cwd-scoped build is unchanged.
+function with_profile_in(
+	invocation: string,
+	profile: AgentProfile,
+	cwd: string,
+	session_id?: string,
+): AgentArgvResult {
+	const diagnostic = agent_diagnostics.check(profile)
+	if (diagnostic.kind === 'rejected') return diagnostic
+
+	return { kind: 'argv', argv: build(invocation, profile, cwd, session_id), profile }
+}
+
+// A resume build under the same profile diagnostics as `with_profile_in`, so a lane re-dispatch that
+// resumes a session runs the identical readiness check a fresh one does (joshuafolkken/kit#2317).
+function with_resume_in(
+	invocation: string,
+	profile: AgentProfile,
+	session_id: string,
+	cwd: string,
+): AgentArgvResult {
+	const diagnostic = agent_diagnostics.check(profile)
+	if (diagnostic.kind === 'rejected') return diagnostic
+
+	return { kind: 'argv', argv: build_resume(invocation, profile, session_id, cwd), profile }
+}
+
+function with_profile(invocation: string, profile: AgentProfile): AgentArgvResult {
+	const diagnostic = agent_diagnostics.check(profile)
+	if (diagnostic.kind === 'rejected') return diagnostic
+
+	return { kind: 'argv', argv: build(invocation, profile), profile }
+}
+
+function resolve(
+	invocation: string,
+	role: AgentRole,
+	environment: AgentEnvironment = process.env,
+): AgentArgvResult {
+	const resolved = agent_role_profile.resolve(role, environment)
+
+	return resolved.kind === 'rejected' ? resolved : with_profile(invocation, resolved.profile)
+}
+
+// **A cut relaunch's profile, resolved for the phase the resumed child is entering**
+// (joshuafolkken/kit#2382). A stored lane profile keeps its model and takes only the phase's effort; a
+// lane without one resolves the worker for the phase. An env override wins over the phase in either path.
+function resume_argv(
+	invocation: string,
+	profile: AgentProfile | undefined,
+	phase: string,
+	cwd: string,
+): AgentArgvResult {
+	if (profile !== undefined) {
+		return with_profile_in(invocation, agent_role_profile.with_phase_effort(profile, phase), cwd)
+	}
+
+	const resolved = agent_role_profile.resolve(agent_role_profile.WORKER, process.env, phase)
+
+	return resolved.kind === 'rejected'
+		? resolved
+		: with_profile_in(invocation, resolved.profile, cwd)
+}
+
+function resolve_in(
+	invocation: string,
+	role: AgentRole,
+	cwd: string,
+	environment: AgentEnvironment = process.env,
+): AgentArgvResult {
+	const resolved = agent_role_profile.resolve(role, environment)
+
+	return resolved.kind === 'rejected'
+		? resolved
+		: with_profile_in(invocation, resolved.profile, cwd)
+}
+
+const agent_argv = {
+	build,
+	build_resume,
+	resolve,
+	resolve_in,
+	resume_argv,
+	with_profile,
+	with_profile_in,
+	with_resume_in,
+}
+
+export type { AgentArgv, AgentArgvResult }
+export { agent_argv }