@joshuafolkken/kit 1.872.0

package/scripts/run/run-wake-describe.ts

@@ -0,0 +1,97 @@
+import { agent_role_profile } from '#scripts/agent/agent-role-profile'
+import { run_carry, type CarryRead } from './run-carry'
+import { run_event_stream } from './run-event-stream'
+import { run_liveness } from './run-liveness'
+import { run_wake, type RunWake } from './run-wake'
+
+// The `--list` presentation of a wake record (joshuafolkken/kit#2407 split it out of `run-wake-cli.ts`,
+// which had reached its line limit). What the command *does* stays in the CLI; how a supervisor's
+// record reads back to a person lives here, one cohesive block.
+
+const UNKNOWN_CUTS = 'an unreadable number of'
+const STOP_COMMAND = 'pnpm josh run:wake --stop'
+
+// The three paths every verb needs: the carry record it reads, its own record, and the work tree a
+// woken session runs in. The work tree is the common git directory's parent, which is the *primary*
+// checkout — a lane must never be where the next session resumes, because a lane belongs to one child.
+interface WakeContext {
+	carry_target: string
+	wake_target: string
+	// Where everything this supervisor starts writes its output (joshuafolkken/kit#1746). It is named
+	// in `--list` and in every warning, because a path nobody is told is a file nobody reads.
+	log_target: string
+	// The run's event stream, keyed on the primary checkout's git directory — the one the resumed
+	// `backlogrun` parent runs in, so its own git directory is this common one, exactly the key the emit
+	// side uses. `--list` relays the newest event from here: the report surface belongs to the run, and
+	// `--list` is the degenerate last-event read of the same stream the attached session follows
+	// (joshuafolkken/kit#2207).
+	event_target: string
+	worktree: string
+}
+
+function carry_cuts(read: CarryRead): string {
+	if (read.kind === 'carried' || read.kind === 'expired') return String(read.carry.cuts)
+
+	return UNKNOWN_CUTS
+}
+
+// **A wake that has gone out and has not been answered is said out loud** (joshuafolkken/kit#1746).
+// Read from `woke` and `cuts` alone, the forty minutes a supervisor spends retrying one lost cut look
+// exactly like the second before its first launch — so a person checking on a stalled backlog was
+// shown nothing to check. `attempts` is present only while a cut is unserved, which is why its
+// absence is what prints nothing.
+function outstanding_line(wake: RunWake): string | undefined {
+	if (wake.attempts === undefined) return undefined
+
+	return `${String(wake.attempts)} launch(es) outstanding for the current cut, none claimed yet`
+}
+
+// The run's stream, read here because a headless parent's progress reaches its own transcript alone —
+// after a cut, `--list` is the person's one window onto it (joshuafolkken/kit#1910). Two lines: the
+// newest event (the degenerate last-event read of the stream the watch pane follows, so `--list` and
+// the pane read one stream rather than two paths), and how to watch on from here in a pane of its own —
+// the same surface before and after the cut, with `tail -F` on the raw stream named as a recovery path
+// rather than the ambient one (joshuafolkken/kit#2207, joshuafolkken/kit#2492). The event line is
+// omitted before the first event, the way `outstanding_line` omits a count of zero; the watch line is
+// always shown.
+function stream_lines(context: WakeContext): Array<string> {
+	const event = run_event_stream.read_last(context.event_target)
+	const progress = event === undefined ? [] : [`progress: ${run_event_stream.format_event(event)}`]
+	const follow = `watch: \`pnpm josh run:event --watch ${String(event?.pos ?? 0)}\` in a pane of its own (recover with \`tail -F ${context.event_target}\`)`
+
+	return [...progress, follow]
+}
+
+// The wake count is printed beside the carry record's `cuts` rather than alone, because their relation
+// is the property worth being able to check — one wake per cut, plus one per crashed session the
+// supervisor recovered (joshuafolkken/kit#2336), so `woke >= cuts` and the gap is the recoveries.
+// `woke < cuts` is the shortfall that says a cut went unserved, and since joshuafolkken/kit#1746 `woke`
+// counts records actually claimed rather than sessions started.
+// **The outstanding line beside it is what makes a shortfall readable**: the count is observed at a
+// poll, so it lags a claim by up to one interval, and launches still outstanding are what say whether
+// a missing wake is one not yet seen or one that never arrived.
+function describe_wake(wake: RunWake, context: WakeContext): string {
+	const live = run_wake.is_supervisor_live(wake) ? 'running' : 'not running'
+	const cuts = carry_cuts(run_carry.read_carry(context.carry_target))
+
+	return [
+		`invocation: ${wake.invocation}`,
+		`profile: ${wake.profile === undefined ? 'unrecorded' : agent_role_profile.describe(wake.profile)}`,
+		`supervisor: process ${String(wake.pid)} (${live}), watching since ${wake.started_at}`,
+		`woke ${String(wake.woke)} session(s) across ${cuts} cut(s)`,
+		outstanding_line(wake),
+		run_liveness.describe_agent_state(context.log_target),
+		`output: ${context.log_target}`,
+		// How progress is seen without asking after the cut: the run's stream, followed from here
+		// (joshuafolkken/kit#2207). `--list` is that reader's one-shot last-event form.
+		...stream_lines(context),
+		`stop it with \`${STOP_COMMAND}\``,
+	]
+		.filter((line) => line !== undefined)
+		.join('\n')
+}
+
+const run_wake_describe = { STOP_COMMAND, describe_wake }
+
+export type { WakeContext }
+export { run_wake_describe }

package/scripts/run/run-wake-driver.ts

@@ -0,0 +1,80 @@
+import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
+import { run_carry, type CarryRead } from './run-carry'
+import { run_invocation } from './run-invocation'
+import type { DriveResult } from './run-wake-loop'
+
+const SUCCESS = 0
+const FIRST_LINE = 0
+const RESUME_PREFIX = 'resume: '
+
+function driver_args(invocation: string): ReadonlyArray<string> | undefined {
+	const rebuilt = run_invocation.rebuild(invocation)
+	if (rebuilt !== invocation) return undefined
+	const named_count = run_invocation.issue_numbers(rebuilt)?.length ?? 0
+
+	return [
+		'backlog:drive',
+		'--owner',
+		String(process.pid),
+		...rebuilt.split(' ').slice(1 + named_count),
+	]
+}
+
+function is_final_stop(verdict: string | undefined, read: CarryRead): boolean {
+	return verdict?.startsWith('stop') === true && read.kind === 'none'
+}
+
+function handoff_material(verdict: string, resume: string, details: string): string {
+	const context = details === '' ? '' : `\nDetails: ${details}`
+	const epic = verdict.startsWith('epic #')
+		? '\nThe named item is an epic. Follow backlogrun-steps.md named epic procedure; do not launch the epic root as a fullrun child. After all children merge or park, record the root with pnpm josh run:carry --done <epic-number> --owner "$PPID" before continuing to the next named item.'
+		: ''
+
+	return `Driver result: ${verdict}\n${resume}${context}${epic}`
+}
+
+function driver_result(out: string, read: CarryRead, details = ''): DriveResult {
+	const lines = out.split('\n')
+	const verdict = lines[FIRST_LINE]
+
+	if (is_final_stop(verdict, read)) return { kind: 'finished' }
+	const resume = lines.find((line) => line.startsWith(RESUME_PREFIX))
+
+	if (verdict === undefined || resume === undefined) {
+		return { kind: 'failed', note: `backlog:drive returned an incomplete result: ${out}` }
+	}
+
+	return { kind: 'judgment', material: handoff_material(verdict, resume, details) }
+}
+
+function read_result(result: JoshResult, target: string): DriveResult {
+	if (result.code !== SUCCESS) return { kind: 'failed', note: result.err ?? result.out }
+
+	return driver_result(result.out, run_carry.read_carry(target), result.err)
+}
+
+function claim_record(target: string, invocation: string): boolean {
+	const current = run_carry.read_carry(target)
+	if (current.kind !== 'carried' || current.carry.invocation !== invocation) return false
+	if (current.carry.is_handed_off !== true && run_carry.is_owner_live(current.carry)) return false
+
+	return run_carry.adopt_carry(target, current.carry, run_carry.owner_of(process.pid)) !== undefined
+}
+
+async function drive(target: string): Promise<DriveResult> {
+	const read = run_carry.read_carry(target)
+	if (read.kind !== 'carried') return { kind: 'failed', note: 'The carry record changed.' }
+
+	const args = driver_args(read.carry.invocation)
+	if (args === undefined) return { kind: 'failed', note: 'The carried invocation is invalid.' }
+
+	if (!claim_record(target, read.carry.invocation)) {
+		return { kind: 'failed', note: 'The driver could not claim the carry record.' }
+	}
+
+	const result = await josh_command.josh_run(args, true)
+
+	return read_result(result, target)
+}
+
+export const run_wake_driver = { drive, driver_args, driver_result }

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

@@ -0,0 +1,29 @@
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { run_carry } from './run-carry'
+
+// The supervisor's recovery hand-off (joshuafolkken/kit#2437). A session that claimed the carry record
+// and then died without `run:carry --cut` leaves it `carried`, owned by a gone process, with no
+// hand-off. `run-wake.ts` → `decide_not_handed_off` already re-wakes on that record (#2336), but the
+// successor it woke then ran `--begin` over a record no cut handed off and was answered `standing` —
+// "stop for a person" — so the recovery ended the run it existed to continue.
+//
+// **The fix is to make the recovery a cut, not to teach the successor a second answer.** Before it
+// launches, the supervisor writes the same `is_handed_off` a `--cut` writes, so the successor's
+// `--begin` classifies `resume` through the one path a declared cut already takes, and `standing` is
+// left meaning what `backlogrun-steps.md` says it means: a record nobody is watching.
+//
+// It writes only where the record is `carried` and not already handed off, so on the ordinary path —
+// a hand-off a cut already declared — it touches nothing. The dead-owner test is the caller's: the loop
+// reaches a launch on an un-handed-off record only through `decide_not_handed_off`'s dead-owner branch.
+
+function hand_off(target: string): void {
+	const read = run_carry.read_carry(target)
+
+	if (read.kind !== 'carried' || read.carry.is_handed_off === true) return
+
+	stamp_file.write_stamp(target, { ...read.carry, is_handed_off: true })
+}
+
+const run_wake_handoff = { hand_off }
+
+export { run_wake_handoff }

package/scripts/run/run-wake-loop.ts

@@ -0,0 +1,223 @@
+import type { CarryRead } from './run-carry'
+import {
+	run_wake,
+	type RunWake,
+	type WakeDecision,
+	type WakeDecisionInput,
+	type WakeStopReason,
+} from './run-wake'
+import type { LaunchResult } from './run-wake-session'
+
+// The supervisor's body: read the carry record, decide, act, sleep, repeat (joshuafolkken/kit#1719).
+//
+// **Everything it touches is a port**, so the loop is testable without a real process, a real clock or
+// a real Telegram. What is left here is the sequencing, which is the part worth pinning: a run that
+// woke twice for one cut, or that stopped on a record it had not re-read, would be wrong in a way no
+// unit test of `decide` alone could see.
+//
+// **The supervisor re-reads its own record every pass, and that is how `--stop` works.** Removing the
+// record is the stop signal; the signal sent alongside it only shortens the wait. So a stop is honored
+// even where the process cannot be signalled, and the supervisor never outlives a record a person
+// deliberately removed.
+
+const STOPPED_REASON: WakeStopReason = 'stopped'
+const FAILED_REASON: WakeStopReason = 'failed'
+const NO_ATTEMPTS = 0
+const STOPPED_BY_PERSON: LoopStop = { reason: STOPPED_REASON, note: undefined }
+// **The back-off after repeated whiffs, and its ceiling** (joshuafolkken/kit#2417). While a launch is
+// deferred for want of work, each wait is as long as the idle stretch so far — so the polling interval
+// doubles pass by pass — capped at this multiple of the configured one. Eight times the one-minute
+// default is eight minutes: far fewer backlog reads over a long empty stretch, and still well inside
+// the idle ceiling, so work that appears is picked up within one capped wait.
+const MAX_BACKOFF_FACTOR = 8
+
+interface LoopPorts {
+	// The carry record, re-read every pass rather than cached: it is written by the parent loop of a
+	// different session, which is the whole point of reading it here.
+	read_carry: () => CarryRead
+	// Whether the process named on the carry record is still running. The cutting session writes
+	// `--cut` and then exits, so the two moments are not the same one and the supervisor has to wait
+	// out the second — `run-wake.ts` → `WakeDecisionInput.is_owner_live`.
+	is_owner_live: (read: CarryRead) => boolean
+	// A compatibility probe for the wake decision. Production lets the resident driver inspect work,
+	// including an empty idle watch, without starting an AI session.
+	has_work: (read: CarryRead) => Promise<boolean | undefined>
+	// **The forced transcript id is generated here and handed to `wake`** (joshuafolkken/kit#2407), so
+	// the loop stays deterministic under test — a fixture returns a known id — while production draws a
+	// fresh UUID. The same id is recorded on the wake record, which is how `josh time --run` later knows
+	// the session was one this supervisor started.
+	new_session_id: () => string
+	// Hands the carry record from the supervisor-owned driver to a judgment session.
+	hand_off: () => void
+	// Runs the deterministic backlog driver. A normal completion never calls `wake`.
+	drive: () => Promise<DriveResult>
+	wake: (invocation: string, session_id: string, material: string) => LaunchResult
+	sleep: (milliseconds: number) => Promise<void>
+	now: () => Date
+}
+
+type DriveResult =
+	{ kind: 'finished' } | { kind: 'judgment'; material: string } | { kind: 'failed'; note: string }
+
+interface LoopStop {
+	reason: WakeStopReason
+	// What went wrong, where anything did. It is what the completion warning quotes, so a failure never
+	// reaches the person as a bare verdict they then have to go and diagnose.
+	note: string | undefined
+}
+
+type StepOutcome = { kind: 'continue'; wake: RunWake } | { kind: 'stop'; stop: LoopStop }
+
+function stopped(reason: WakeStopReason, note?: string): StepOutcome {
+	return { kind: 'stop', stop: { reason, note } }
+}
+
+// The grace window elapsing is the launch-failure detector, so the note has to say what was expected
+// rather than only that something failed — the person reading it has no other record of the attempt.
+// **The last process is named because it is not killed**: a session that is merely slow is still doing
+// the run's work, so the warning hands the person something to check rather than destroying it.
+function wake_failure_note(wake: RunWake): string {
+	const attempts = String(wake.attempts ?? NO_ATTEMPTS)
+	const last = wake.woke_pid === undefined ? 'none' : `process ${String(wake.woke_pid)}`
+
+	return `woke a session for "${wake.invocation}" ${attempts} time(s) and none of them claimed the carry record; the last one was ${last}, which may still be running`
+}
+
+// The hand-off is written before the launch, never after: a successor that boots fast enough to run
+// `--begin` before a post-launch write would read the record un-handed-off and be answered `standing`.
+async function wake_step(wake: RunWake, ports: LoopPorts): Promise<StepOutcome> {
+	const driven = await ports.drive()
+	if (driven.kind === 'finished') return stopped('ended')
+	if (driven.kind === 'failed') return stopped(FAILED_REASON, driven.note)
+
+	const session_id = ports.new_session_id()
+
+	ports.hand_off()
+
+	const result = ports.wake(wake.invocation, session_id, driven.material)
+
+	if (result.kind === 'failed') return stopped(FAILED_REASON, result.note)
+
+	return { kind: 'continue', wake: run_wake.count_wake(wake, ports.now(), result.pid, session_id) }
+}
+
+// A `wait` means the woken session has claimed the carry record, so the wake mark is cleared and the
+// next cut starts the grace window afresh — **and it is the only pass on which `woke` may grow**
+// (joshuafolkken/kit#1746), because arriving here is the supervisor observing that a record it was
+// waiting on has been taken over. A `hold` starts the ceiling on a wait without launching
+// anything — the bounded wait on a predecessor that has cut but not yet exited, which ends the moment
+// that predecessor does. A `pending` keeps what is there, because the window it is measured from is
+// still open.
+function continue_step(wake: RunWake, decision: WakeDecision, ports: LoopPorts): StepOutcome {
+	if (decision.kind === 'wait') return { kind: 'continue', wake: run_wake.count_claim(wake) }
+
+	if (decision.kind === 'hold') {
+		return { kind: 'continue', wake: run_wake.mark_wait(wake, ports.now()) }
+	}
+
+	if (decision.kind === 'idle') {
+		return { kind: 'continue', wake: run_wake.mark_idle(wake, ports.now()) }
+	}
+
+	return { kind: 'continue', wake }
+}
+
+async function step(wake: RunWake, decision: WakeDecision, ports: LoopPorts): Promise<StepOutcome> {
+	if (decision.kind === 'stop') return stopped(decision.reason)
+	if (decision.kind === 'failed') return stopped(FAILED_REASON, wake_failure_note(wake))
+	if (decision.kind === 'wake') return await wake_step(wake, ports)
+
+	return continue_step(wake, decision, ports)
+}
+
+// `has_work` starts as "cannot tell", which never defers anything — so this first input decides every
+// branch except whether a launch has work to go to.
+function decision_input(wake: RunWake, ports: LoopPorts): WakeDecisionInput {
+	const read = ports.read_carry()
+
+	return {
+		read,
+		woke_at: wake.woke_at,
+		attempts: wake.attempts ?? NO_ATTEMPTS,
+		is_owner_live: ports.is_owner_live(read),
+		held_at: wake.held_at,
+		has_work: undefined,
+		idle_since: wake.idle_since,
+		now: ports.now(),
+	}
+}
+
+// **Work is asked about only where the answer could change the decision** (joshuafolkken/kit#2417):
+// on a pass the record alone would launch from. Every other pass — the in-flight wait, the pending
+// grace window, the hold — decides from the record as before and costs no backlog read.
+async function decide_pass(wake: RunWake, ports: LoopPorts): Promise<WakeDecision> {
+	const input = decision_input(wake, ports)
+	const decision = run_wake.decide(input)
+
+	if (decision.kind !== 'wake') return decision
+
+	return run_wake.decide({ ...input, has_work: await ports.has_work(input.read) })
+}
+
+// The wait before the next pass: the configured interval, stretched while a launch is being deferred
+// to the length of the idle stretch so far and capped at `MAX_BACKOFF_FACTOR` times the interval.
+function next_interval(wake: RunWake | undefined, interval_ms: number, now: Date): number {
+	const idle_since = wake?.idle_since === undefined ? NaN : Date.parse(wake.idle_since)
+
+	if (Number.isNaN(idle_since)) return interval_ms
+
+	const stretched = Math.max(interval_ms, now.getTime() - idle_since)
+
+	return Math.min(stretched, interval_ms * MAX_BACKOFF_FACTOR)
+}
+
+// The record is re-read at the top of every pass rather than carried in a variable, so a `--stop` that
+// removed it ends the loop at the next interval and a `--list` reads what the loop actually wrote.
+// One pass: decide, act, write the result back. `undefined` means carry on to the next interval.
+async function run_pass(
+	target: string,
+	wake: RunWake,
+	ports: LoopPorts,
+): Promise<LoopStop | undefined> {
+	const outcome = await step(wake, await decide_pass(wake, ports), ports)
+
+	if (outcome.kind === 'stop') return outcome.stop
+
+	return run_wake.update_wake(target, outcome.wake) ? undefined : STOPPED_BY_PERSON
+}
+
+// The record is re-read at the top of every pass rather than carried in a variable, so a `--stop` that
+// removed it ends the loop at the next interval and a `--list` reads what the loop actually wrote.
+//
+// **`read_own_wake` rather than `read_wake`, and the difference is a whole pass** (joshuafolkken/kit#1727).
+// A record that has become a *successor's* is not this loop's to act on, and reading it back would
+// have this pass decide from another supervisor's counters — spawning a session for a cut that
+// supervisor is already serving, and only then finding the write-back refused. Read as owned or not
+// at all, the replaced loop ends here, quietly and before it does anything: the run is not
+// unattended, because the supervisor that took the record over is watching it.
+async function run_loop(target: string, ports: LoopPorts, interval_ms: number): Promise<LoopStop> {
+	let wake = run_wake.read_own_wake(target)
+
+	while (wake !== undefined) {
+		const stop = await run_pass(target, wake, ports)
+
+		if (stop !== undefined) return stop
+
+		await ports.sleep(next_interval(run_wake.read_own_wake(target), interval_ms, ports.now()))
+		wake = run_wake.read_own_wake(target)
+	}
+
+	return STOPPED_BY_PERSON
+}
+
+const run_wake_loop = {
+	FAILED_REASON,
+	MAX_BACKOFF_FACTOR,
+	STOPPED_REASON,
+	next_interval,
+	run_loop,
+	step,
+}
+
+export type { DriveResult, LoopPorts, LoopStop }
+export { run_wake_loop }

package/scripts/run/run-wake-session.ts

@@ -0,0 +1,150 @@
+import { agent_argv, type AgentArgvResult } from '#scripts/agent/agent-argv'
+import { agent_role_profile, type AgentProfile } from '#scripts/agent/agent-role-profile'
+import { claude_agent_argv } from '#scripts/agent/claude-agent-argv'
+import { detached_launch, type LaunchArgv } from './detached-launch'
+import { run_invocation } from './run-invocation'
+
+// How the supervisor starts things: the next agent session, and — at `--start` — its own detached
+// self. Both go through one `launch`, because the two differ only in what is being run
+// (joshuafolkken/kit#1719).
+//
+// **The launch itself is no longer this file's** (joshuafolkken/kit#1749). `detached-launch.ts` holds
+// it, because a delegated child dispatched into a lane needs the same mechanism and none of the
+// invocation parsing this supervisor needs. What stays here is the constants naming the agent CLI and
+// the two argument vectors this supervisor composes.
+//
+// **The invocation grammar is no longer this file's either** (joshuafolkken/kit#1774; folded into
+// `backlogrun` by joshuafolkken/kit#1984). `run-carry.ts` reads the same grammar to say which of a
+// `backlogrun`'s named issues are still outstanding — so it is `run-invocation.ts`'s, imported
+// rather than restated. What that move does **not** change is the rebuild-from-constants design: the
+// invocation handed to the agent CLI is still composed out of that module's own constants and
+// validated integers; a judgment handoff adds the driver's result after that validated invocation.
+//
+// **The agent CLI is a constant, not configuration, and it is the Claude adapter's constant.** It was
+// an environment variable first (`JOSH_WAKE_COMMAND`), which put the choice of *which binary runs* in
+// reach of anything that can set an environment — and this binary runs unattended, overnight, in the
+// person's own checkout with the person's own credentials. Shape-checking the name does not address
+// that; removing the choice does. The two names below are aliases of that one constant rather than a
+// second copy of it (joshuafolkken/kit#1749).
+//
+// **The waker adds nothing to what may be run.** The argument vector is the constant command plus an
+// invocation rebuilt to say exactly what the record said, and nothing here writes a label: `auto-ok`
+// stays a person's to apply, so a woken session is offered by exactly the rules the first one was. A
+// pool that grew across the seam is `backlogrun-steps.md` → "What one invocation approves", not the
+// waker's doing (joshuafolkken/kit#1675).
+const WAKE_COMMAND = claude_agent_argv.AGENT_COMMAND
+const WAKE_FLAGS = claude_agent_argv.AGENT_FLAGS
+const LOOP_FLAG = '--loop'
+const INTERVAL_FLAG = '--interval'
+const SUPERVISOR_SESSION = 'run-wake-supervisor'
+
+function scheduler_profile(): AgentProfile | undefined {
+	const resolved = agent_role_profile.resolve(agent_role_profile.SCHEDULER)
+	if (resolved.kind === 'profile') return resolved.profile
+
+	console.error(resolved.note)
+
+	return undefined
+}
+
+function supervisor_environment(profile: AgentProfile): Record<string, string> {
+	return profile.provider === 'openai'
+		? { CODEX_THREAD_ID: SUPERVISOR_SESSION }
+		: { CLAUDE_CODE_CHILD_SESSION: SUPERVISOR_SESSION }
+}
+
+// **What comes back is always the rebuilt text, and it is refused unless it matches the record.** The
+// two requirements are separate. Returning the rebuilt string is what severs the flow from the file;
+// requiring it to match is what keeps the wake usable, because the woken session hands its prompt
+// straight back to `run:carry --begin`, where `is_handed_off_to` compares it to the record character
+// for character. A record the rebuild would rewrite — odd spacing, or a value written `05` — is
+// therefore refused here, and the supervisor stops at once with a note, where waking on it would launch
+// three sessions that each decline to claim the record and take half an hour to say so.
+//
+// It goes on the command line last and as one argument, never interpolated into a command string: it is
+// the prompt the woken session is given, not a list of arguments to the agent CLI. The split happens
+// here, to read the record; the pieces are one argument again before they leave.
+function safe_invocation(invocation: string): string | undefined {
+	if (!detached_launch.is_safe_value(invocation)) return undefined
+
+	const rebuilt = run_invocation.rebuild(invocation)
+
+	return rebuilt === invocation ? rebuilt : undefined
+}
+
+// **The two failure modes are kept apart, not folded into one `undefined`** (joshuafolkken/kit#1932).
+// An unmatched or unsafe invocation is `undefined` and the caller names it as one; a rejected effort
+// override carries the role resolver's own note through the `rejected` variant, so a
+// `JOSH_SCHEDULER_EFFORT` typo is reported as the env typo it is rather than as unreadable carried text.
+// **`session_id` forces the woken session's transcript id, and only where a work tree is given**
+// (joshuafolkken/kit#2407). A wake always resolves both a profile and the primary checkout, so it
+// reaches the `with_profile_in` branch; the cwd-less branch stays for callers that force nothing.
+function profiled_argv(
+	invocation: string,
+	profile: AgentProfile,
+	cwd?: string,
+	session_id?: string,
+): AgentArgvResult {
+	return cwd === undefined
+		? agent_argv.with_profile(invocation, profile)
+		: agent_argv.with_profile_in(invocation, profile, cwd, session_id)
+}
+
+function resolved_argv(invocation: string, cwd?: string): AgentArgvResult {
+	return cwd === undefined
+		? agent_argv.resolve(invocation, agent_role_profile.SCHEDULER)
+		: agent_argv.resolve_in(invocation, agent_role_profile.SCHEDULER, cwd)
+}
+
+function wake_argv(
+	invocation: string,
+	profile?: AgentProfile,
+	cwd?: string,
+	session?: string | { id: string; material: string },
+): AgentArgvResult | undefined {
+	const matched = safe_invocation(invocation)
+	if (matched === undefined) return undefined
+	const prompt =
+		typeof session === 'object' ? `${matched}\n\nDriver handoff:\n${session.material}` : matched
+	const session_id = typeof session === 'object' ? session.id : session
+
+	return profile === undefined
+		? resolved_argv(prompt, cwd)
+		: profiled_argv(prompt, profile, cwd, session_id)
+}
+
+// Re-invoking this very script under the same runner, which is what makes the supervisor outlive the
+// session that started it. `execArgv` is carried across rather than dropped, because the loader flags
+// are what let the runner execute a TypeScript entry point at all — without them the detached process
+// starts and immediately fails on the syntax.
+//
+// **The interval is forwarded rather than dropped.** `--start --interval 15` accepts the flag, so a
+// supervisor that then polled at the default would be silently ignoring what it was told.
+function supervisor_argv(script_path: string, interval?: string): LaunchArgv {
+	const chosen = interval === undefined ? [] : [INTERVAL_FLAG, interval]
+
+	return {
+		command: process.execPath,
+		args: [...process.execArgv, script_path, LOOP_FLAG, ...chosen],
+	}
+}
+
+// **`ensure_log`, `is_safe_argv` and `launch` are re-exported rather than reimplemented.** They are
+// `detached-launch.ts`'s now; naming them here keeps `run:wake`'s own callers reading one namespace,
+// and there is exactly one implementation behind both names (joshuafolkken/kit#1749).
+const run_wake_session = {
+	INTERVAL_FLAG,
+	LOOP_FLAG,
+	WAKE_COMMAND,
+	WAKE_FLAGS,
+	ensure_log: detached_launch.ensure_log,
+	is_safe_argv: detached_launch.is_safe_argv,
+	launch: detached_launch.launch,
+	scheduler_profile,
+	supervisor_argv,
+	supervisor_environment,
+	wake_argv,
+}
+
+export type { LaunchRequest, LaunchResult } from './detached-launch'
+export { run_wake_session }