@open-tomato/rafa 0.45.0 → 0.46.0

package/dist/core/loop/claude.d.ts

@@ -0,0 +1,388 @@
+/**
+ * Spawning a Claude session, and reading how much of the plan's budget
+ * has gone.
+ *
+ * {@link runClaude} is the loop's door onto the CLI for a session whose
+ * output only the operator reads. It has one call site, the CI-repair
+ * session in `start/pr-lifecycle.ts`, which is not routed — one model,
+ * one effort, every tool. So the flags are a parameter with an EMPTY
+ * default: `runClaude(prompt, settingSources)` spawns the base
+ * arguments and the setting sources, and nothing a declaration could
+ * add.
+ *
+ * {@link runClaudeCaptured} is the door for a session whose output the
+ * LOOP reads as well. It has three callers: the per-task dispatch,
+ * through `runTaskSession` in `start/dispatch.ts`, the wrap-up session
+ * in `start/wrap-up.ts` and the backfill proposal pass in
+ * `backfill/propose.ts`. Plan generation in the `claude` planner,
+ * `adapters/planner/claude.ts`, which `plan.ts` makes, captures its
+ * session through the same spawner without that door, for the reason
+ * the search runner does below. Each of the four parses what its
+ * session wrote: a task session ends its final message
+ * with a `rafa:report` block, the wrap-up with a `rafa:promoted` one
+ * when it was listed lessons to promote (`start/promoted-check.ts`), a
+ * plan session ends its final message with a `rafa:spec-review` one,
+ * and a proposal session's answer goes through `parseSessionAnswer`.
+ * The wrap-up, like a task session, also hands over the flags serving
+ * it the rafa-tier winners (`start/serving.ts`), and is not routed.
+ * {@link spawnClaude} answers the exit code alone, so a loop holding
+ * that session's exit code holds nothing else. A task session's flags are
+ * the ones its routing declaration resolved to, with the
+ * `--session-id` the loop picked for that session ahead of them and
+ * its served flags (`start/serving.ts`) ahead of both, and the planner
+ * hands over none: its argument list is `claudeArgs(settingSources)`. The captured entry builds its argument
+ * list through the same {@link claudeArgs} and hands the prompt over the
+ * same way; only the spawner differs, {@link spawnClaudeCaptured} piping
+ * stdout, echoing it on to the operator as it arrives and keeping the
+ * same bytes for the answer. It sits BESIDE `runClaude` rather than
+ * replacing its spawner, so in text mode a session nothing parses keeps
+ * spawning exactly what it spawned before. What json mode changes is in
+ * the section "What reaches the operator" below.
+ *
+ * The search runner (`inventory/search/index.ts`) captures its one
+ * session through the same spawner without going through
+ * `runClaudeCaptured`: it builds its argument list with
+ * {@link claudeArgs} and hands the spawner its one option,
+ * {@link CapturedSpawnOptions.cwd}, since that session runs inside the
+ * scratch copy of its candidates. The epic verification runner
+ * (`epic/verify-run.ts`) does the same for each check session, which
+ * runs inside a worktree made for the run, and the `claude` planner for
+ * its plan session, which runs in the project root `rafa plan` resolved
+ * rather than in the caller's directory (#171). The loop's sessions
+ * name the same option through `runClaude` and `runClaudeCaptured`,
+ * which take it last: each task, wrap-up and CI repair session runs in
+ * the run's checkout (`start/checkout.ts`), a linked worktree's own
+ * directory when the loop runs in one, and never in the directory the
+ * process happens to stand in.
+ *
+ * The flags land AFTER {@link CLAUDE_BASE_ARGS} and the setting sources
+ * rather than before, and the ordering is load-bearing rather than
+ * cosmetic. `--tools` is
+ * VARIADIC in the CLI's own help (`--tools <tools...>`), so it keeps
+ * consuming tokens until one that starts with a dash. `--tools` is the
+ * LAST flag `resolveDeclarationFlags` emits, and the resolved flags are
+ * the last thing appended here, so its value is the final element of
+ * the argument list with nothing after it to be swallowed. Putting the
+ * resolved flags FIRST would put `-p` behind that variadic, which is
+ * the one arrangement that breaks. `-p` itself takes no value
+ * (`-p, --print` is a boolean in the same help text), so nothing after
+ * it is at risk either.
+ *
+ * ## Setting sources
+ *
+ * Every session, through either door, is spawned with
+ * {@link SETTING_SOURCES_FLAG} naming the run's `loop.settingSources`
+ * (`config.ts`), `project,local` unless a config names others. Finding
+ * 3 of `.rafa/specs/phase-1-installable.md` measured the user scope at about
+ * 14,900 tokens of a 58,989-token turn. The sources are a REQUIRED
+ * parameter of {@link claudeArgs} and of both doors. A default here
+ * would be a second one beside `CONFIG_DEFAULTS`, and a caller that
+ * forgot to hand on the value its config resolved to would spawn under
+ * that default with nothing to say so; with no default, that caller
+ * does not compile.
+ *
+ * They go between the base arguments and the flags. The CLI's help, on
+ * Claude Code 2.1.268, lists `--setting-sources <sources>` as one
+ * comma-separated value where `--tools <tools...>` is variadic, so the
+ * sources swallow nothing and `--tools` stays last. What they change is
+ * measurable without a model call: an `--agent` name no scope defines
+ * exits 1 and lists the agents it could have run. That list held this
+ * repo's `.claude/agents` and none of `~/.claude/agents` under
+ * `project,local`, both under `user,project,local`, and neither under
+ * `local`.
+ *
+ * The prompt goes on STDIN and never into the argument list. That is
+ * not a style choice: a plan's task prompt here is the injected
+ * instructions plus `PROMPT.md` plus the plan, the whole file under the
+ * `full` injection mode and in every wrap-up prompt, which is far past
+ * what an argument list can carry, and an argument list is also
+ * visible to every `ps` on the machine.
+ *
+ * {@link ClaudeSpawner} exists because the real spawn is
+ * `Bun.spawn` and the root suite runs vitest under NODE — measured,
+ * `globalThis.Bun` is `undefined` and `process.versions.bun` is null
+ * in that runtime. So the default spawner cannot be driven from a test
+ * at all, and the seam is what makes the argument list an assertion
+ * rather than something inferred from a session that appeared to work.
+ *
+ * ## What reaches the operator
+ *
+ * A session's stdout reaches the operator in the mode of the active
+ * output (`core/output/active.ts`). In text mode it is the bytes the
+ * session wrote, in the order it wrote them: {@link spawnClaude} inherits
+ * the stream, and {@link spawnClaudeCaptured} writes each chunk to
+ * `process.stdout` as it arrives. In json mode those bytes would put
+ * lines no NDJSON reader parses among the events, so neither door lets
+ * them through. {@link spawnClaudeCaptured} hands each line, its newline
+ * off, to the active output's `info`, which the `json` adapter writes as
+ * one `log` event. The `events` mode routes them the same way, and its
+ * adapter drops every `info`, so the screen keeps only its `rafa·` lines.
+ * {@link spawnClaude} spawns through
+ * {@link spawnClaudeCaptured} and answers its exit code alone. A last
+ * line with no newline goes once stdout closes, and a blank line is an
+ * event with an empty message, so the messages joined with newlines are
+ * the session's stdout. The argument list, the prompt, the environment
+ * and the inherited stderr are the same in both modes.
+ *
+ * The environment is `sessionSpawnEnv(process.env)` at both doors
+ * (`session-env.ts`), the one function a reading of the session's
+ * environment calls too, so neither door spells an entry of its own.
+ * That puts the running entry's `bundled/bin` at the front of every
+ * session's `PATH`.
+ *
+ * ## Interrupting a running session
+ *
+ * Both doors hold the process they spawn among the live sessions until it
+ * has exited, and {@link interruptClaudeSessions} sends each of those
+ * SIGINT. `loop start` calls it from its own SIGINT handler (`src/start.ts`).
+ * A terminal's Ctrl-C reaches the loop and its session at once, as one
+ * process group, but `rafa loop stop` signals the loop's pid alone, and a
+ * signal to that pid never reaches the session. Measured on 2026-09-15 by
+ * spawning `loop start` over a stand-in `claude` sleeping 20 seconds: a
+ * SIGINT to the loop's pid ended the run after 20.06 s, once the session
+ * had run to its own end, and one to its process group after 0.03 s.
+ *
+ * A signalled session has ended once its process exits, but the captured
+ * door reads the session's stdout to its end first, and a process the
+ * session left behind holding that stdout keeps it open. Measured on
+ * 2026-09-15 with a stand-in that trapped SIGINT and exited 130 while a
+ * sleep it had put in the background held the pipe: `rafa loop stop` took
+ * 19.9 s, ending when the sleep did, against 0.28 s with the sleep's output
+ * sent to `/dev/null`. Both doors answered 130 for a stand-in the signal
+ * ended, under bun 1.3.14.
+ *
+ * ## The spend guard
+ *
+ * Both doors warn when the running command's `spends` declaration
+ * (`packages/rafa/src/core/command/spends.ts`) does not cover the session they start,
+ * and start it anyway: usage is never a gate. The running command is the
+ * one the dispatcher recorded with its parsed flags
+ * (`packages/rafa/src/core/command/running.ts`).
+ * The check runs once per session, before `Bun.spawn`: {@link spawnClaude}
+ * in json mode hands its session to the same unchecked spawner
+ * {@link spawnClaudeCaptured} uses rather than to that door, and so does
+ * not warn a second time.
+ *
+ * A run is covered when its command declares `always` or `through`, a
+ * `with` declaration and the run carries the flag, or an `unless`
+ * declaration and the run does not. `through` covers a run because the
+ * command runs another's action in-process (`rafa next`,
+ * `src/next/actions.ts`), and the recorded command stays the outer one.
+ * A flag is matched by its name without the dashes, and `--no-<name>`
+ * also as the parser keys it, `<name>` set to `false`; a flag recorded
+ * as `false` is not carried. With no command recorded, as for a caller
+ * that never went through the dispatcher, nothing is warned.
+ *
+ * The warning is one `warn` line at the active output, `⚠️  ` and then
+ * {@link spendWarning}'s sentence, which names the command as typed
+ * after `rafa` and says to declare `spends` on it, with the flag missing
+ * for a `with` form and the flag present for an `unless` one. It changes
+ * no exit code. In text mode it is a `warn:` line on the output's one
+ * stream (`packages/rafa/src/core/output/text.ts`); in json mode a `log` event at
+ * level `warn`; in events mode nothing, since that output drops `warn`.
+ */
+import type { RunningCommand } from '../command/running.js';
+import type { ClaudeSettingSource } from '../config/config-sections.js';
+/**
+ * The executable every session is spawned as.
+ *
+ * Resolved on PATH rather than by absolute path, which is what lets a
+ * version manager or a shim answer for it.
+ */
+export declare const CLAUDE_BIN = "claude";
+/**
+ * Arguments every session gets, before any resolved flag.
+ *
+ * `-p` prints and exits, which is what makes the session
+ * non-interactive; `--dangerously-skip-permissions` is what lets it
+ * run unattended. Neither is a task's to choose, so neither is
+ * reachable from a declaration.
+ */
+export declare const CLAUDE_BASE_ARGS: readonly string[];
+/**
+ * The flag every session names its setting sources with. See the
+ * module note.
+ */
+export declare const SETTING_SOURCES_FLAG = "--setting-sources";
+/**
+ * Builds the argument list for one session: the base arguments, the
+ * setting sources, the served flags, then the flags.
+ *
+ * `settingSources` is the run's resolved `loop.settingSources`, joined
+ * with commas in the order given. `config.ts` has already refused a
+ * source the CLI does not name, a repeat and an empty list, so nothing
+ * is checked again here.
+ *
+ * `flags` is whatever a task's declaration resolved to, already
+ * validated and already ordered by its own resolver. Nothing is
+ * reordered, deduped or filtered here: this module has no opinion on
+ * which flags are legal, and one that did would be a second authority
+ * for a decision `core/plan/declaration.ts` already makes.
+ *
+ * `served` is `ServedSet.flags` from `serveResolution`
+ * (`src/tiers/serve.ts`), the session-only flags handing the run's
+ * served directory over, and is taken as it is for the same reason.
+ * It defaults to empty, so a caller that serves nothing spawns what it
+ * spawned before. It goes BEFORE `flags`, never after: `--tools` has to
+ * stay the last element (see the module note), and the served flags
+ * are safe ahead of the resolved ones, since `serve.ts` ends them with
+ * `--agents <json>` when an agent is served and every resolved flag
+ * starts with a dash, which is where the variadic `--add-dir` stops.
+ */
+export declare function claudeArgs(settingSources: readonly ClaudeSettingSource[], flags?: readonly string[], served?: readonly string[]): string[];
+/**
+ * Runs `claude` with an argument list and a prompt on stdin, and
+ * answers the exit code.
+ *
+ * The seam every test drives, since the default {@link spawnClaude}
+ * cannot run under the root suite's runtime.
+ */
+export type ClaudeSpawner = (args: readonly string[], prompt: string, options?: CapturedSpawnOptions) => Promise<number>;
+/**
+ * Sends SIGINT to every session either door spawned and has not yet seen
+ * exit, and answers how many that is. A process that exited before its
+ * door saw it is signalled too, which does nothing: measured under bun
+ * 1.3.14, `kill` on a subprocess that has exited throws nothing. See the
+ * module note.
+ */
+export declare function interruptClaudeSessions(): number;
+/**
+ * True when `flags` carry `flag`, written as typed with its dashes: its
+ * name is recorded as anything but `false`, or, for a `--no-<name>`
+ * flag, `<name>` is recorded as `false`, which is how the parser keys it.
+ */
+export declare function carriesFlag(flags: RunningCommand['flags'], flag: string): boolean;
+/**
+ * Why `running`'s declaration does not cover the session it starts, as a
+ * sentence, or null when it does or nothing is recorded.
+ */
+export declare function spendWarning(running: RunningCommand | null): string | null;
+/**
+ * The real spawner: `Bun.spawn`, streams inherited so the session's
+ * output reaches the operator as it happens, in the working directory
+ * `options.cwd` names, or the loop's own when it names none.
+ *
+ * In json or events mode it spawns through {@link spawnClaudeCaptured}
+ * instead and answers that session's exit code, so the session's stdout
+ * reaches the active output's `info` and never the screen as bytes; see
+ * the module note.
+ *
+ * An exit code of `undefined` — which is what a signalled process
+ * answers — is reported as 1, because every caller here treats a
+ * non-zero as a failed session and a killed one is not a success.
+ *
+ * Warns, and spawns anyway, when the running command's `spends` does not
+ * cover the run; see the module note.
+ */
+export declare function spawnClaude(args: readonly string[], prompt: string, options?: CapturedSpawnOptions): Promise<number>;
+/**
+ * Spawns one Claude session with `prompt` on stdin, loading settings
+ * from `settingSources`.
+ *
+ * `flags` defaults to empty, so the CI-repair session, which hands
+ * over none, cannot be routed by accident: it spawns the base arguments
+ * and its setting sources with no routing flag. `settingSources` has
+ * no default; see the module note.
+ *
+ * `served` is the flags handing a served directory over, which
+ * {@link claudeArgs} places between the setting sources and `flags`. It
+ * defaults to empty, and the CI repair hands none. `options` is where
+ * the session runs, handed to the spawner as it is; the CI repair names
+ * the run's checkout there (`start/pr-lifecycle.ts`). Both come last so
+ * that no call written before they existed has to change.
+ */
+export declare function runClaude(prompt: string, settingSources: readonly ClaudeSettingSource[], flags?: readonly string[], spawn?: ClaudeSpawner, served?: readonly string[], options?: CapturedSpawnOptions): Promise<number>;
+/**
+ * What a captured session answers: its exit code, and everything it
+ * wrote to stdout, decoded as UTF-8.
+ */
+export interface CapturedSession {
+    readonly exitCode: number;
+    readonly stdout: string;
+}
+/**
+ * Where a captured session runs. Every field is optional, and an empty
+ * object spawns exactly what no options spawn.
+ */
+export interface CapturedSpawnOptions {
+    /**
+     * The session's working directory, or the loop's own when absent. The
+     * search session (`src/inventory/search/index.ts`) names the scratch
+     * copy of its candidates, each check session of the epic verification
+     * run (`src/epic/verify-run.ts`) a detached worktree of main, the plan
+     * session of the `claude` planner (`src/adapters/planner/claude.ts`)
+     * the project root it writes the plan under, and the loop's task,
+     * wrap-up and CI repair sessions the run's checkout
+     * (`src/start/checkout.ts`).
+     */
+    readonly cwd?: string;
+}
+/**
+ * Runs `claude` with an argument list and a prompt on stdin, and
+ * answers the exit code together with the session's stdout.
+ *
+ * A seam of its own rather than a widened {@link ClaudeSpawner}:
+ * widening that one would change what every existing `runClaude`
+ * double has to answer, for sessions whose output nothing reads. The
+ * third parameter is optional for the same reason: a double written
+ * for `(args, prompt)` is still a `CapturingSpawner`.
+ */
+export type CapturingSpawner = (args: readonly string[], prompt: string, options?: CapturedSpawnOptions) => Promise<CapturedSession>;
+/**
+ * The capturing spawner: `Bun.spawn` with stdout PIPED, each chunk
+ * written on to the operator's stdout as it arrives and kept for the
+ * answer.
+ *
+ * Everything else matches {@link spawnClaude}: the executable, the
+ * prompt on stdin, the environment. The working directory is the
+ * loop's own unless `options.cwd` names another, as it is for
+ * {@link spawnClaude}. Stderr stays inherited, so the
+ * operator sees it and the capture never holds it, and a report parsed
+ * out of `stdout` cannot have been a warning line.
+ *
+ * The bytes go through ONE streaming `TextDecoder`, never a decode per
+ * chunk, because a pipe read can end inside a character. Measured on
+ * bun 1.3.14, a `€` written in two halves arrived as the chunks
+ * `78 e2` and `82 ac 79`; decoded chunk by chunk that is three U+FFFD
+ * replacement characters where the streaming decoder answers the `€`.
+ * The decoder is not `fatal`, so bytes that are not UTF-8 at all
+ * become U+FFFD rather than a rejection.
+ *
+ * The answer waits for stdout to CLOSE as well as for the exit, which
+ * is what reading a pipe to its end means: a process the session left
+ * behind that still holds the pipe holds the answer too. Measured, a
+ * shell that backgrounded a `sleep 1.5` exited at 17ms and closed its
+ * stdout at 1,530ms.
+ *
+ * A signalled session needs no fallback here. Measured on bun 1.3.14,
+ * `exited` answers 128 plus the signal number (137 for a SIGKILL)
+ * while `exitCode` is null, so a killed session is already a non-zero,
+ * which every caller reads as a failure.
+ *
+ * When a write to the operator throws, the call rejects with that
+ * error, but only once the session has EXITED. Stopping the read does
+ * not stop the process: measured, a shell writing into a pipe whose
+ * reader had quit kept running, each write failing with `Broken pipe`,
+ * until it was killed 3s later. Rejecting at once would hand the loop
+ * back a tree that a session is still changing.
+ *
+ * Warns, and spawns anyway, when the running command's `spends` does not
+ * cover the run; see the module note.
+ */
+export declare function spawnClaudeCaptured(args: readonly string[], prompt: string, options?: CapturedSpawnOptions): Promise<CapturedSession>;
+/**
+ * Spawns one Claude session with `prompt` on stdin, and answers its
+ * exit code together with everything it wrote to stdout.
+ *
+ * The argument list is the one {@link runClaude} builds for the same
+ * setting sources and flags, both going through {@link claudeArgs}, so
+ * capturing a session changes where its stdout goes and nothing about
+ * what is run. The operator still sees that output as it is written,
+ * through the tee in {@link spawnClaudeCaptured}.
+ *
+ * `served` and `options` are taken as {@link runClaude} takes them. The
+ * task session (`runTaskSession` in `start/dispatch.ts`) and the wrap-up
+ * (`start/wrap-up.ts`) are the two callers that hand any, and both name
+ * the run's checkout as the session's working directory.
+ */
+export declare function runClaudeCaptured(prompt: string, settingSources: readonly ClaudeSettingSource[], flags?: readonly string[], spawn?: CapturingSpawner, served?: readonly string[], options?: CapturedSpawnOptions): Promise<CapturedSession>;

package/dist/core/loop/hop-record.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The shapes of the hop record and of a place, with the checks that read
+ * them from parsed JSON: the part of `src/next/hop-record.ts` and
+ * `src/project/position.ts` a session record needs (`sessions.ts` keeps a
+ * hop record in its `hop` field).
+ *
+ * It sits in core so `sessions.ts` reads them without importing above
+ * core. `src/project/position.ts` re-exports `Place` and `asPlace`, and
+ * `src/next/hop-record.ts` re-exports `HopKind`, `HopState`, `HopRecord`
+ * and `asHopRecord`, each under the same name; the reading and writing of
+ * `.rafa/position.json` and `.rafa/hop.json`, and the module notes that
+ * describe both files, stay there. `isRecord` is exported for the
+ * position's own check in `position.ts`.
+ *
+ * The file imports nothing.
+ */
+/** A (board, epic) pair of issue numbers; `epic` is null on a board with no epic chosen. */
+export interface Place {
+    readonly board: number;
+    readonly epic: number | null;
+}
+/** Why the hop went: H's blocker, or a home epic that ran dry. */
+export type HopKind = 'blocker' | 'dry';
+/** Where the hop stands: working its target, back home waiting on it or with it merged, or back home from a halt. */
+export type HopState = 'away' | 'waiting' | 'merged' | 'halted';
+/** The record `.rafa/hop.json` holds; see the module note of `src/next/hop-record.ts`. */
+export interface HopRecord {
+    readonly kind: HopKind;
+    readonly home: Place;
+    readonly from: Place;
+    /** H, the home issue its blocker stopped; null on a dry hop. */
+    readonly blocked: number | null;
+    /** C, H's blocker the hop works; null on a dry hop. */
+    readonly target: number | null;
+    readonly targetEpic: number;
+    readonly targetBoard: number;
+    readonly state: HopState;
+    /** The target's pull request, null before it is opened. */
+    readonly pullRequest: number | null;
+    /** ISO 8601. */
+    readonly startedAt: string;
+}
+/** True for a plain object. */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/** `value` as a place, or null when it is not one; the hop record reads its places through it. */
+export declare function asPlace(value: unknown): Place | null;
+/**
+ * `value` as a hop record, or null when it is not one: the check
+ * `readHopRecord` (`src/next/hop-record.ts`) makes on the parsed file,
+ * which the session record makes on its `hop` field (`sessions.ts`).
+ */
+export declare function asHopRecord(value: unknown): HopRecord | null;

package/dist/core/loop/index.d.ts

@@ -0,0 +1,179 @@
+/**
+ * The barrel over the loop's session records and its doors onto the
+ * Claude CLI: every name `sessions.ts`, `claude.ts`, `session-env.ts` and
+ * `suite-failure.ts` export, and nothing else.
+ *
+ * A file outside `packages/rafa/src/core/` imports this file and never the two behind
+ * it (`scripts/survey/core-barrels.ts` measures that, and
+ * `src/tests/core-barrels.sweep.test.ts` holds it against the tree). A
+ * file inside `packages/rafa/src/core/` imports the two directly and never this file:
+ * `session-readings.ts` and the six test files of `sessions.ts` import
+ * that file, and `packages/rafa/src/core/adapters/registry.ts` and
+ * `claude.test.ts` import `claude.ts`. `index.test.ts`, this file's own
+ * test, is the one file of `packages/rafa/src/core/` that imports it.
+ *
+ * ## What sits behind it
+ *
+ *   - `sessions.ts`: the session records of `loop start`, one JSON file
+ *     per run under `<root>/.rafa/runs/`, with their reads, the state a
+ *     record reads as, the refusal of a second run of a plan, and the
+ *     writes;
+ *   - `claude.ts`: the two doors a Claude session is spawned through,
+ *     the argument list both build, the spawners behind them, the
+ *     interrupt of the sessions still running, and the spend guard's
+ *     sentence;
+ *   - `session-env.ts`: the environment a Claude session is spawned
+ *     with, which `claude.ts` imports by path;
+ *   - `suite-failure.ts`: the type of one failing test, which
+ *     `sessions.ts` imports by path and `src/suite/run.ts` re-exports.
+ *
+ * The four files share no name, and only `sessions.ts` imports
+ * `suite-failure.ts`, for a type. One
+ * import of this barrel loads both: a file that takes `isPidAlive`
+ * alone loads `claude.ts` with it.
+ *
+ * The reading of one record is `session-record-parse.ts`, beside
+ * `sessions.ts`, which imports it by path: the sets a record's fields
+ * are checked against, `parseSessionRecord`, `SessionRecordError` and
+ * the readers of the optional fields. It was
+ * `src/loop/session-record-parse.ts` until it moved here, and a
+ * re-export stays at that path. `sessions.ts` re-exports what a caller
+ * of a record reads from there, four types and thirteen runtime names,
+ * and this barrel carries them with the rest, so the parser takes no
+ * line of its own here. So a file outside `packages/rafa/src/core/` that reads a
+ * record needs this one import, as it needed `sessions.ts` alone before
+ * the move.
+ *
+ * ## Why `claude.ts` is here
+ *
+ * A barrel is split when it would close a runtime cycle, and never
+ * otherwise. `claude.ts` was the third file to move into this folder,
+ * and it closes none behind this barrel, so it took no barrel of its
+ * own. The section "Why the barrel closes no cycle" holds the
+ * measurement.
+ *
+ * ## Why the session readings are not here
+ *
+ * `packages/rafa/src/core/loop/` has three barrels, all listed under `CORE_BARRELS` in
+ * `scripts/survey/core-moves.ts`. `session-readings.ts`, the second
+ * file that moved here, sits alone behind `readings.ts`. It reaches
+ * `packages/rafa/src/effort/store/development-build.ts` by value, through
+ * `packages/rafa/src/effort/store/task-finishes.ts`, and that file imports three
+ * runtime names from this barrel. With `session-readings.ts` behind
+ * this barrel the store would import this file, and this file the
+ * store: a cycle of six files. `readings.ts` records the measurement,
+ * and `readings.test.ts` holds that no name is on both barrels.
+ *
+ * ## Why the hop record is not here
+ *
+ * `hop-record.ts`, the shapes of the hop record and of a place, sits
+ * alone behind `hops.ts`. `src/next/hop-record.ts` and
+ * `src/project/position.ts` re-export its names, so they import a
+ * barrel over it by value, and `src/loop/session-record-parse.ts`,
+ * which `sessions.ts` imported by value, imported `asHopRecord` from
+ * `src/next/hop-record.ts` by value when the split was made; it has
+ * since moved here and imports `hop-record.ts` by path. With `hop-record.ts` behind this
+ * barrel that is a cycle of four files: this one, `sessions.ts`, the
+ * parser and `src/next/hop-record.ts`. `hops.ts` records the
+ * measurement, and `hops.test.ts` holds that no name is on two loop
+ * barrels. `sessions.ts` imports `hop-record.ts` by path, for
+ * `HopRecord`.
+ *
+ * ## Why the barrel closes no cycle
+ *
+ * A barrel that groups a file with a file outside `packages/rafa/src/core/` that
+ * imports the barrel back by value is a runtime cycle. `sessions.ts`
+ * imported three files by value when it moved:
+ * `packages/rafa/src/core/config/config-sections.ts`, for `messageOf`, and two outside
+ * `packages/rafa/src/core/`, `src/loop/session-record-parse.ts` and
+ * `src/project/scope.ts`. Through them it reached 38 files by value, and
+ * none of the 38 imported it by value. Both have since moved into
+ * `packages/rafa/src/core/`, as `session-record-parse.ts` beside it and
+ * `packages/rafa/src/core/config/scope.ts`.
+ *
+ * The parser, then `src/loop/session-record-parse.ts`, imported this
+ * barrel for the record's interfaces with `import type` alone, which is
+ * erased before anything loads; since it moved here as
+ * `session-record-parse.ts` it imports `sessions.ts` by path, the same
+ * way. Its own note says why its sets, its error and its id check live
+ * on its side: so that it takes no value from `sessions.ts`. That rule
+ * holds this barrel as well.
+ *
+ * Measured when the file moved: the value imports of the non-test files
+ * under `src/` and `packages/` held six cycles before the move and the
+ * same six after it, none through a file of this folder. The control,
+ * the same tree with `src/loop/session-record-parse.ts` taking one
+ * function (`errorCode`) from this barrel and calling it inside a
+ * function, held a seventh: this file, `sessions.ts` and that one.
+ *
+ * That seventh loaded in the three orders tried: this file,
+ * `sessions.ts` and `src/loop/session-record-parse.ts` each imported
+ * first in a fresh `bun` process, then one record parsed through this
+ * barrel. A second control took a `const` (`RUNS_DIR`) instead and read
+ * it at the top level of `src/loop/session-record-parse.ts`. It loaded
+ * when that file came first, and failed with
+ * `ReferenceError: Cannot access 'RUNS_DIR' before initialization.`
+ * when this file or `sessions.ts` did. The barrel holds the rule rather
+ * than the first reading.
+ *
+ * `src/tests/import-cycle.sweep.test.ts` would have refused both
+ * controls. It fails on a cycle across two clusters of
+ * `docs/survey/cluster-map.json`, which places `sessions.ts` in c2 and
+ * `src/loop/session-record-parse.ts` in c3; this file, which the map
+ * does not name, lands in c2 by its folder. Read the way the sweep
+ * reads the graph, each control held one cross-cluster cycle and the
+ * tree as moved held none.
+ *
+ * `claude.ts` imports four files by value: three of `packages/rafa/src/core/`,
+ * `packages/rafa/src/core/command/command.ts` for `commandSpelling`,
+ * `packages/rafa/src/core/command/running.ts` for the running command and
+ * `packages/rafa/src/core/output/active.ts` for the active output, and one outside
+ * it, `src/utils/session-env.ts`, which has since moved here as
+ * `session-env.ts`. When it moved, `running.ts` was still
+ * `src/cli/running.ts`; through the four it reached 13 files by value, and none of the 13
+ * imported this barrel or `claude.ts` by value. None of the 38 files
+ * `sessions.ts` reached did either. Eleven non-test files imported
+ * `claude.ts` by value before the move and import this barrel since.
+ *
+ * Measured when `claude.ts` moved: the same six cycles before the move
+ * and after it, none through a file of this folder, with this barrel
+ * reaching 46 files by value. The control, the same tree with
+ * `src/utils/session-env.ts` taking `CLAUDE_BIN` from this barrel and
+ * returning it from a function, held a seventh of three files: this
+ * file, `claude.ts` and that one.
+ *
+ * That seventh loaded in the three orders tried: each of the three
+ * files imported first in a fresh `bun` process, then `claudeArgs`
+ * called and `CLAUDE_BIN` and `RUNS_DIR` read through this barrel. A
+ * second control read `CLAUDE_BIN` at the top level of
+ * `src/utils/session-env.ts` instead. It loaded when that file came
+ * first, and failed with
+ * `ReferenceError: Cannot access 'CLAUDE_BIN' before initialization.`
+ * when this file or `claude.ts` did.
+ *
+ * The map places `claude.ts` in c3 and `src/utils/session-env.ts` in
+ * c4. The folder's two mapped files now tie, one in c2 and one in c3,
+ * and a tie goes to the name that sorts first, so this file still lands
+ * in c2. Read the way the sweep reads the graph, the first control held
+ * one cross-cluster cycle, c2 with c3 and c4, and the tree as moved
+ * held none.
+ *
+ * ## What it exports
+ *
+ * Each name is spelled, types apart from values, as the other core
+ * barrels spell theirs. No name here is part of the published surface:
+ * `src/index.ts` re-exports nothing from this file.
+ *
+ * `index.test.ts` holds the list to the four files: every name each
+ * exports is here once, as the same binding, the first three share no name, the
+ * names `sessions.ts` re-exports are the bindings
+ * `session-record-parse.ts` declares, and no other name is
+ * here.
+ */
+export type { PidProbe, SessionChange, SessionConflict, SessionConflictReason, SessionDecision, SessionDraft, SessionPhase, SessionReadSeams, SessionRecord, SessionState, SessionStep, SessionStepKind, SessionStepOnly, SessionStepReason, SessionTask, SessionTaskRef, } from './sessions.js';
+export type { CapturedSession, CapturedSpawnOptions, CapturingSpawner, ClaudeSpawner } from './claude.js';
+export type { SpawnEnv } from './session-env.js';
+export type { SuiteFailure } from './suite-failure.js';
+export { beginSession, errorCode, isPidAlive, isPositiveWhole, isSessionId, parseSessionRecord, readSession, readSessions, readState, RECORD_EXTENSION, RUNS_DIR, runsDir, samePlan, SESSION_DECISION_STRATEGIES, SESSION_PHASES, SESSION_STATES, SESSION_STEP_KINDS, SESSION_STEP_REASONS, SessionConflictError, sessionConflicts, sessionDecisions, sessionFilePath, sessionPhase, SessionRecordError, SessionStateError, sessionSteps, updateSession, } from './sessions.js';
+export { carriesFlag, CLAUDE_BASE_ARGS, CLAUDE_BIN, claudeArgs, interruptClaudeSessions, runClaude, runClaudeCaptured, SETTING_SOURCES_FLAG, spawnClaude, spawnClaudeCaptured, spendWarning, } from './claude.js';
+export { sessionPath, sessionSpawnEnv } from './session-env.js';

package/dist/core/loop/session-env.d.ts

@@ -0,0 +1,20 @@
+/** An environment as `process.env` and `Bun.spawn` spell it. */
+export type SpawnEnv = Record<string, string | undefined>;
+/**
+ * `base`'s `PATH` with `binDir` in front, or `binDir` alone for a base
+ * with no `PATH` or an empty one. See "`bundled/bin` goes first on
+ * `PATH`".
+ */
+export declare function sessionPath(base: string | undefined, binDir: string): string;
+/**
+ * The environment every session is spawned with: `base`, plus the two
+ * entries a session must see whichever spawner started it.
+ *
+ * `PATH` is `binDir`, the running entry's `bundled/bin` unless another
+ * is handed, in front of `base`'s own ({@link sessionPath}).
+ * `CLAUDE_CODE_ENTRYPOINT` is set to `cli` over whatever `base` holds
+ * for it, so a shell that already carries another value still spawns
+ * `cli`. Every other entry of `base` is handed on as it is, an entry
+ * holding `undefined` included.
+ */
+export declare function sessionSpawnEnv(base: Readonly<SpawnEnv>, binDir?: string): SpawnEnv;