@open-tomato/rafa 0.44.0 → 0.46.0

package/dist/core/loop/session-record-parse.d.ts

@@ -0,0 +1,63 @@
+import type { SessionDecision, SessionRecord, SessionStep } from './sessions.js';
+/** The states a session record holds, in the spec's order. */
+export declare const SESSION_STATES: readonly ['running', 'paused', 'stopped', 'done'];
+/** One of {@link SESSION_STATES}. */
+export type SessionState = (typeof SESSION_STATES)[number];
+/**
+ * The phases of a run, in the order a run meets them: its tasks, the
+ * wrap-up, the pull request, the CI wait, and a repair of what CI failed.
+ */
+export declare const SESSION_PHASES: readonly ['task', 'wrap-up', 'pull-request', 'ci', 'repair'];
+/** One of {@link SESSION_PHASES}. */
+export type SessionPhase = (typeof SESSION_PHASES)[number];
+/** What a record's file name ends in. */
+export declare const RECORD_EXTENSION = ".json";
+/** The kinds of suite step a run records, in the order a run meets them. */
+export declare const SESSION_STEP_KINDS: readonly ['baseline', 'task', 'stage', 'pre-wrap-up'];
+/** One of {@link SESSION_STEP_KINDS}. */
+export type SessionStepKind = (typeof SESSION_STEP_KINDS)[number];
+/**
+ * Why a suite step ran at the scope it did: the task's own `tests=`
+ * declaration, a full-suite trigger, the `--changed` fallback taken when
+ * no `Owns:` folder narrows the run, a `tests=module` task whose module
+ * holds no test file, and a stage step's own scope.
+ */
+export declare const SESSION_STEP_REASONS: readonly ['declared', 'trigger', 'fallback', 'no-module-tests', 'stage'];
+/** One of {@link SESSION_STEP_REASONS}. */
+export type SessionStepReason = (typeof SESSION_STEP_REASONS)[number];
+/** The strategies a saved decision may name: the two that pass over a task. */
+export declare const SESSION_DECISION_STRATEGIES: readonly ['jump', 'defer'];
+/** A record file that cannot be read, or holds no record this module accepts. */
+export declare class SessionRecordError extends Error {
+    /** The record's path. */
+    readonly file: string;
+    constructor(file: string, problem: string);
+}
+/** True when the text can name a record file. */
+export declare function isSessionId(value: string): boolean;
+/** True for a whole number from 1. */
+export declare function isPositiveWhole(value: unknown): value is number;
+/** Every problem with one step, the `at` naming its place in the record. */
+export declare function stepProblems(step: unknown, at: string): string[];
+/** Every problem with a parsed record read from `file`. */
+export declare function recordProblems(fields: object, file: string): string[];
+/**
+ * A frozen record of fields already checked, in the order it is written;
+ * `phase`, `hop`, `worktree`, `steps` then `decisions` last, each only
+ * when there, `phase` only when it is one of {@link SESSION_PHASES}.
+ */
+export declare function freezeRecord(fields: object): SessionRecord;
+/** The steps a record holds, oldest first; none for a record written before the field. */
+export declare function sessionSteps(record: Pick<SessionRecord, 'steps'>): readonly SessionStep[];
+/** The pass-over list a record saved; none for a record without the key. */
+export declare function sessionDecisions(record: Pick<SessionRecord, 'decisions'>): readonly SessionDecision[];
+/**
+ * The phase a record reads as: its own, or `task` for a record without
+ * one, as a record from a rafa older than the field is.
+ */
+export declare function sessionPhase(record: Pick<SessionRecord, 'phase'>): SessionPhase;
+/**
+ * Reads a record out of the text of `file`, or throws
+ * {@link SessionRecordError} naming every problem. See the module note.
+ */
+export declare function parseSessionRecord(text: string, file: string): SessionRecord;

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

@@ -0,0 +1,408 @@
+/**
+ * The session records of `loop start`: one JSON file per run under
+ * `<root>/.rafa/runs/`, named by the session's id.
+ *
+ * `.rafa/specs/cli-surface.md`, "Sessions": `loop stop`, `pause`, `resume`,
+ * `status` and `list` act on a run through its record, so every
+ * `loop start` writes `.rafa/runs/<session-id>.json`. This module reads,
+ * judges and writes those files, and prints nothing. `start/session.ts`
+ * is where `loop start` calls it.
+ *
+ * ## The record
+ *
+ * A {@link SessionRecord}, written as indented JSON:
+ *
+ *   - `sessionId`: the run's id, the file's name before `.json`.
+ *   - `planStub`: the plan's stub, or null for a plan whose file name
+ *     carries none, as `PLAN.md` does (`core/plan/plan-stamp.ts`).
+ *   - `plan`: the plan's path relative to the project root. The spec lists
+ *     the stub alone; the path is what tells two stubless plans apart.
+ *   - `branch`: the branch the run was started on.
+ *   - `pid`: the process running the loop.
+ *   - `startedAt`: when the run began, as an ISO timestamp.
+ *   - `state`: one of {@link SESSION_STATES}.
+ *   - `task`: the task running, its 1-based tracker line and its sentence,
+ *     or null.
+ *   - `phase`: where the run is, one of {@link SESSION_PHASES}: `task`
+ *     while it works its plan's tasks, then `wrap-up`, `pull-request`,
+ *     `ci` and `repair`. The field is additive, as `steps` is: a record
+ *     written before it, and a new record, carry no `phase` key, and
+ *     {@link sessionPhase} reads such a record as `task`. A phase this
+ *     rafa does not know, as a later rafa may write, is no problem on
+ *     read and reads as `task` too; it is left out of the record read,
+ *     so the next write of the record carries no `phase` key. It is
+ *     written as its own `"phase": "<value>"` key, as `state` is, which
+ *     the zsh prompt plugin's patterns over the file's text rely on
+ *     (`extras/zsh/rafa-prompt/`). Once written, every later write keeps
+ *     it until a change names another ({@link SessionChange}'s `phase`).
+ *   - `hop`: only on a run started with `loop start --roadmap` while a
+ *     `rafa next --roadmap` hop is away, the hop record as
+ *     `.rafa/hop.json` held it when the run began
+ *     (`src/next/hop-record.ts`, `start/session.ts`). A record of any
+ *     other run carries no `hop` key at all, never one set to null, so
+ *     such a record is written byte for byte as it was before the field.
+ *     Once written, every later write of the record keeps it as it is.
+ *   - `worktree`: only on a run whose checkout is a linked worktree rather
+ *     than the project root, as a `loop start --as-worktree` run's is, the
+ *     absolute path of that worktree (`start/session.ts`). A run in the
+ *     main checkout carries no `worktree` key at all, as it carries no
+ *     `hop`, and every later write keeps the path as it is.
+ *   - `steps`: the suite steps the runner has recorded for the run, oldest
+ *     first, each a {@link SessionStep}. The field is additive: a record
+ *     written before it, and a run that has recorded no step, carry no
+ *     `steps` key at all, and {@link sessionSteps} reads such a record as
+ *     holding none. A stored `steps: []` reads the same way and is written
+ *     back without the key. Steps are only ever appended
+ *     ({@link SessionChange}'s `appendStep`); every later write keeps them.
+ *   - `decisions`: the pass-over list of a `loop start --continue` run
+ *     (`start/pass-over.ts`), each a {@link SessionDecision}: the task
+ *     jumped or deferred, its `lineNum` counted from 0 as the tracker
+ *     reader counts it, its text with the blocker comment and
+ *     declaration off, and its `ordinal`, which copy of that text it is
+ *     among the tracker's task lines (left out of a record from before
+ *     the field, and read as 1), the strategy, `jump` or `defer`, the
+ *     decision's reason, and on a defer alone the task it waits on, as
+ *     `after`. A later run of the plan reads it back off the newest
+ *     ended record, stopped or done, and matches each task by its text
+ *     and ordinal.
+ *     The field is additive, as `steps` is: a record carries no
+ *     `decisions` key until a change hands a list, an empty list is
+ *     written without the key, and
+ *     {@link sessionDecisions} reads such a record as holding none. A
+ *     change's list replaces the stored one whole
+ *     ({@link SessionChange}'s `decisions`); every other write keeps it.
+ *
+ * ## Steps
+ *
+ * A {@link SessionStep} is one suite run the runner made for the run:
+ *
+ *   - `kind`: one of {@link SESSION_STEP_KINDS}, `baseline` at the plan's
+ *     first dispatch, `task` after a task commits, `stage` after a stage's
+ *     last task, `pre-wrap-up` before the wrap-up.
+ *   - `scope`: `affected`, `module` or `full` (`TEST_SCOPES`,
+ *     `core/plan/declaration.ts`), or the list of files and folders run, which
+ *     may be empty.
+ *   - `reason`: optional, why the step ran at that scope, one of
+ *     {@link SESSION_STEP_REASONS}: `declared` for the task's own `tests=`
+ *     declaration, `trigger` for a full-suite trigger, `fallback` for the
+ *     `--changed` run taken when no `Owns:` folder narrows it,
+ *     `no-module-tests` for a `tests=module` task whose module holds no
+ *     test file, and `stage` for a stage step's own scope. It is written
+ *     as its own key right after `scope`. A step written by rafa 0.35.0
+ *     or earlier carries no `reason` key and reads as having none; a
+ *     value outside the set is left out on read, never refused, as an
+ *     unknown `phase` is.
+ *   - `command`: the argv spawned, `bun` first, never empty.
+ *   - `exitCode`: the command's exit code, a whole number.
+ *   - `summary`: Bun's `Ran N tests across M files.` line, or null when it
+ *     printed none.
+ *   - `failures`: the failing tests, each a file and a full test name
+ *     (`SuiteFailure`, `suite-failure.ts`).
+ *   - `newFailures`: those of `failures` that are new against the
+ *     baseline; every one of them is also in `failures`, compared by file
+ *     and name. A new failure also carries `errorLines`, after its
+ *     `name`: the first lines of the error Bun printed for it
+ *     (`suite/failure-lines.ts`), which the JUnit report does not hold.
+ *     The key is left out of a failure Bun printed nothing for and of
+ *     every step written before it; a value that is no non-empty list of
+ *     strings is left out on read, never refused, as an unknown `reason`
+ *     is.
+ *   - `stepOnly`: only on a step that reran its newly red test files
+ *     alone and found some green (`start/suite-retake-alone.ts`), each a
+ *     {@link SessionStepOnly}: the file, the names of its tests that were
+ *     red in the step, the error lines Bun printed for the first of
+ *     them, its `position` in the order its `bun test` process ran the
+ *     files, counted from 1, or null when that order did not hold it, and
+ *     `before`, the few files run just before it, in run order. Such a
+ *     file's tests stay in `failures` and are left out of `newFailures`:
+ *     they were red only in the step's own file order. The key is
+ *     written right after `newFailures`. Every other step carries no
+ *     `stepOnly` key, and an entry outside that shape is left out on
+ *     read, never refused, as an unknown `reason` is.
+ *   - `outsideCase`: only on a step whose run exited nonzero and listed
+ *     no failing case (`start/suite-outside-case.ts`), `true`, with
+ *     `outputTail` right after it: the last non-blank lines of that
+ *     run's stderr (`SuiteResult.outputTail`, `suite/run.ts`), which is
+ *     the evidence of a run the JUnit report says nothing about; the
+ *     list is empty when the run printed none. The pair is written
+ *     after `stepOnly`. Every other step carries neither key, so it is
+ *     written byte for byte as it was before them. On read an
+ *     `outsideCase` that is not `true` is left out with the tail, never
+ *     refused, as an unknown `reason` is, and a tail that is no list of
+ *     strings reads as empty.
+ *   - `interrupted`: only on a step the runner read as a stop rather than
+ *     a suite's answer, `true`: its `bun test` ended on SIGINT, or the
+ *     runner received SIGINT while it ran (`start/suite-step.ts`). Its
+ *     failures are what Bun had reported by then, and none of them is new.
+ *     Every other step carries no `interrupted` key at all, never one set
+ *     to false, so it is written byte for byte as it was before the field.
+ *
+ * ## One session is one `loop start`
+ *
+ * A session's id is new for every run, and a rerun of a plan never takes
+ * over an earlier session's record. The preflight's run id is the session
+ * id, and the store refuses a second preflight write under a run id it
+ * already holds (`effort/store/preflight.ts`). Measured on 2026-09-15: the
+ * second `writePreflightChecks` under one id threw
+ * `UNIQUE constraint failed: preflight.run_id, preflight.position`, while
+ * a write under another id went in. A rerun reusing its plan's session
+ * would halt on that refusal whenever the plan names a prerequisite. So a
+ * plan run three times on its branch leaves three records.
+ *
+ * ## The state a record reads as
+ *
+ * A record stored as `running` or `paused` whose pid is gone reads as
+ * `stopped` ({@link readState}): the run ended without writing its end, as
+ * a killed process does. `stopped` and `done` read as stored. A pid is
+ * probed with signal 0, which sends nothing: a process that is gone
+ * answers `ESRCH`, and one that exists under another user `EPERM`, which
+ * reads as alive. A pid the system has handed to an unrelated process
+ * since reads as alive too, so such a record keeps refusing its plan until
+ * it is deleted; the refusal names its file.
+ *
+ * ## Uniqueness over plan, session and branch
+ *
+ * Two records name the same plan when both carry a stub and the stubs are
+ * equal, or neither carries one and the paths are equal
+ * ({@link samePlan}). A stub names the plan wherever its file sits, as
+ * effort attribution reads it. {@link sessionConflicts} refuses a run over
+ * each record of its plan that:
+ *
+ *   - **names another branch**, in whatever state: a plan that has a
+ *     branch does not create another. A revised plan is a new stub, and a
+ *     new stub has no record.
+ *   - **names the run's branch and reads `running` or `paused`**: that
+ *     session is running the plan, and a second run on the same tracker
+ *     would dispatch its tasks twice.
+ *
+ * A record of the plan on the run's branch that reads `stopped` or `done`
+ * refuses nothing. The rerun is a session of its own under the plan and
+ * branch that match, which is the one way a plan runs twice.
+ *
+ * ## Writes
+ *
+ * Every write lands whole: the text goes to a temporary file beside the
+ * record, whose name does not end in `.json`, and is then linked into
+ * place for a new record or renamed over an existing one. The link fails
+ * when the name is taken, so {@link beginSession} never overwrites a
+ * record. A record is checked as it would be read before it is written,
+ * so nothing this module writes is one it refuses to read.
+ *
+ * {@link beginSession} reads the records and writes the new one with no
+ * lock between the two, so two runs of one plan started within that
+ * window both go ahead. The loop is single-thread until phase 6, and the
+ * window is one directory read.
+ *
+ * {@link updateSession} reads the stored record again and changes only
+ * the fields it is handed, so a state another process wrote, as
+ * `loop pause` writes `paused`, survives the loop writing its running
+ * task. A key this module does not know is dropped by that write.
+ *
+ * A change handed `onlyFrom` is refused with {@link SessionStateError},
+ * writing nothing, when the state stored is none of those. `loop pause`
+ * moves only a `running` record and `loop resume` only a `paused` one, so
+ * a run that writes its end between such a command's read and its write
+ * keeps that end. The window left is the one between this module's own
+ * read and its rename, which holds no lock either.
+ *
+ * ## Reading a record
+ *
+ * The record's field readers and {@link parseSessionRecord} live in
+ * `session-record-parse.ts`, beside this file, whose note lists what is
+ * refused on read. This module re-exports what a caller reads from
+ * there, so `./sessions.js` stays the one import a record's reader
+ * needs: `isPositiveWhole` and `RECORD_EXTENSION` among them, which
+ * `src/stretch/folder.ts` and `src/cleanup/runs.ts` read.
+ */
+import type { HopRecord } from './hop-record.js';
+import type { SessionPhase, SessionState, SessionStepKind, SessionStepReason } from './session-record-parse.js';
+import type { SuiteFailure } from './suite-failure.js';
+import type { TestScope } from '../plan/declaration.js';
+export type { SessionPhase, SessionState, SessionStepKind, SessionStepReason, } from './session-record-parse.js';
+export { isPositiveWhole, isSessionId, parseSessionRecord, RECORD_EXTENSION, SESSION_DECISION_STRATEGIES, SESSION_PHASES, SESSION_STATES, SESSION_STEP_KINDS, SESSION_STEP_REASONS, SessionRecordError, sessionDecisions, sessionPhase, sessionSteps, } from './session-record-parse.js';
+/** The directory the records are kept in, under a project's `.rafa/`. */
+export declare const RUNS_DIR = "runs";
+/** The task a session is running. */
+export interface SessionTask {
+    /** The task's line in the tracker, counted from 1. */
+    readonly line: number;
+    /** The task's sentence, its routing declaration left out. */
+    readonly text: string;
+}
+/** One test file red in a step and green when run alone. See the module note, "Steps". */
+export interface SessionStepOnly {
+    /** The test file, relative to the checkout. */
+    readonly file: string;
+    /** The full names of its tests that were red in the step. */
+    readonly tests: readonly string[];
+    /** The error lines Bun printed for the first of them; none when it printed none. */
+    readonly errorLines: readonly string[];
+    /** Its place, from 1, in the order its `bun test` process ran the files; null when that order did not hold it. */
+    readonly position: number | null;
+    /** The files run just before it, in run order. */
+    readonly before: readonly string[];
+}
+/** One suite run the runner recorded for a session. See the module note. */
+export interface SessionStep {
+    readonly kind: SessionStepKind;
+    /** A named scope, or the files and folders run. */
+    readonly scope: TestScope | readonly string[];
+    /** Why the step ran at {@link SessionStep.scope}; left out of a step from rafa 0.35.0 or earlier. See the module note. */
+    readonly reason?: SessionStepReason;
+    /** The argv spawned, `bun` first. */
+    readonly command: readonly string[];
+    readonly exitCode: number;
+    /** Bun's summary line, or null when it printed none. */
+    readonly summary: string | null;
+    readonly failures: readonly SuiteFailure[];
+    /** Those of {@link SessionStep.failures} new against the baseline. */
+    readonly newFailures: readonly SuiteFailure[];
+    /** The files red in the step and green alone; left out of a step with none. See the module note. */
+    readonly stepOnly?: readonly SessionStepOnly[];
+    /** `true` on a step whose run exited nonzero and listed no failing case; left out of every other. See the module note. */
+    readonly outsideCase?: true;
+    /** The last lines of that run's stderr; only beside {@link SessionStep.outsideCase}. */
+    readonly outputTail?: readonly string[];
+    /** `true` on a step read as a stop on SIGINT; left out of every other. See the module note. */
+    readonly interrupted?: true;
+}
+/** A task a saved decision names: its zero-based tracker line and its text. */
+export interface SessionTaskRef {
+    /** Counted from 0, as `TaskInfo.lineNum`; a hint, the text and the ordinal being the key. */
+    readonly lineNum: number;
+    /** The task's text, its blocker comment and declaration off. */
+    readonly task: string;
+    /**
+     * Which copy of `task` it is among the tracker's task lines, ticked
+     * ones included, counted from 1 in tracker order. Left out of a record
+     * written before the field, which reads as 1.
+     */
+    readonly ordinal?: number;
+}
+/** One task a `--continue` run passes over, as its record saves it. See the module note. */
+export interface SessionDecision {
+    readonly task: SessionTaskRef;
+    readonly strategy: 'jump' | 'defer';
+    readonly reason: string;
+    /** On a defer alone: the task it waits on. */
+    readonly after?: SessionTaskRef;
+}
+/** One `loop start` run, as its record holds it. See the module note. */
+export interface SessionRecord {
+    readonly sessionId: string;
+    readonly planStub: string | null;
+    readonly plan: string;
+    readonly branch: string;
+    readonly pid: number;
+    readonly startedAt: string;
+    readonly state: SessionState;
+    readonly task: SessionTask | null;
+    /** Where the run is; left out of a record from before the field. Read it with {@link sessionPhase}. */
+    readonly phase?: SessionPhase;
+    /** The away hop the run was started under; left out of every other run's record. See the module note. */
+    readonly hop?: HopRecord;
+    /** The linked worktree the run's checkout is; left out of a run in the main checkout. See the module note. */
+    readonly worktree?: string;
+    /** The suite steps recorded, oldest first; left out while there are none. Read it with {@link sessionSteps}. */
+    readonly steps?: readonly SessionStep[];
+    /** The pass-over list saved; left out while there is none. Read it with {@link sessionDecisions}. */
+    readonly decisions?: readonly SessionDecision[];
+}
+/** What a new record is made from; it opens `running`, with no task, no phase, no step and no decision. */
+export type SessionDraft = Omit<SessionRecord, 'state' | 'task' | 'phase' | 'steps' | 'decisions'>;
+/** What {@link updateSession} changes. A field left out keeps its stored value. */
+export interface SessionChange {
+    readonly state?: SessionState;
+    readonly task?: SessionTask | null;
+    /** The phase the run is now in. */
+    readonly phase?: SessionPhase;
+    /** A step appended after the stored ones. */
+    readonly appendStep?: SessionStep;
+    /** The pass-over list, replacing the stored one whole; an empty one drops the key. */
+    readonly decisions?: readonly SessionDecision[];
+    /**
+     * The stored states the change acts on. Any other refuses it with
+     * {@link SessionStateError}, writing nothing. Every state when left out.
+     */
+    readonly onlyFrom?: readonly SessionState[];
+}
+/** Answers whether a process with this pid exists. */
+export type PidProbe = (pid: number) => boolean;
+/** The seams a read goes through. */
+export interface SessionReadSeams {
+    /** Whether a pid is alive. {@link isPidAlive} when left out. */
+    readonly isAlive?: PidProbe;
+}
+/** Why a record of the plan refuses a run: its branch, or its live session. */
+export type SessionConflictReason = 'branch' | 'live';
+/** A record refusing a run, and why. */
+export interface SessionConflict {
+    readonly reason: SessionConflictReason;
+    readonly record: SessionRecord;
+}
+/** A run {@link beginSession} refused, over the records that refuse it. */
+export declare class SessionConflictError extends Error {
+    readonly conflicts: readonly SessionConflict[];
+    constructor(conflicts: readonly SessionConflict[]);
+}
+/** A change {@link updateSession} refused: the record stores a state the change does not act on. */
+export declare class SessionStateError extends Error {
+    /** The record's path. */
+    readonly file: string;
+    /** The state the record stores. */
+    readonly state: SessionState;
+    constructor(file: string, state: SessionState, onlyFrom: readonly SessionState[]);
+}
+/** `<root>/.rafa/runs`. */
+export declare function runsDir(root: string): string;
+/** `<root>/.rafa/runs/<sessionId>.json`. Throws on an id {@link isSessionId} refuses. */
+export declare function sessionFilePath(root: string, sessionId: string): string;
+/** The system's code on a thrown error, such as `ENOENT`, or null when it carries none. */
+export declare function errorCode(error: unknown): string | null;
+/**
+ * Whether a process with this pid exists, by signal 0; false for a pid
+ * that is no positive whole number, which is never signalled. See the
+ * module note.
+ */
+export declare function isPidAlive(pid: number): boolean;
+/** The state a record reads as: `running` or `paused` with its pid gone reads `stopped`. */
+export declare function readState(record: SessionRecord, isAlive?: PidProbe): SessionState;
+/**
+ * Every record under `<root>/.rafa/runs/`, each with the state it reads as
+ * ({@link readState}), oldest first. Throws {@link SessionRecordError} for
+ * the first file that holds no record.
+ */
+export declare function readSessions(root: string, seams?: SessionReadSeams): readonly SessionRecord[];
+/**
+ * The record of `sessionId` under `<root>/.rafa/runs/`, with the state it
+ * reads as ({@link readState}). Throws {@link SessionRecordError} when its
+ * file is not there or holds no record, and the error
+ * {@link sessionFilePath} throws for an id it refuses.
+ */
+export declare function readSession(root: string, sessionId: string, seams?: SessionReadSeams): SessionRecord;
+/** Whether two records name the same plan. See the module note. */
+export declare function samePlan(a: Pick<SessionRecord, 'planStub' | 'plan'>, b: Pick<SessionRecord, 'planStub' | 'plan'>): boolean;
+/**
+ * The records refusing a run of `candidate`'s plan on `candidate`'s
+ * branch, in the order handed in. `records` carry the state they read as,
+ * as {@link readSessions} answers them. See the module note.
+ */
+export declare function sessionConflicts(records: readonly SessionRecord[], candidate: Pick<SessionRecord, 'planStub' | 'plan' | 'branch'>): readonly SessionConflict[];
+/**
+ * Opens a session: refuses it with {@link SessionConflictError} when a
+ * record of its plan does ({@link sessionConflicts}), and otherwise writes
+ * its record, `running` with no task, and answers it. Throws
+ * {@link SessionRecordError} when a record cannot be read, and the
+ * system's error when the new one cannot be written, its id's file
+ * already existing included.
+ */
+export declare function beginSession(root: string, draft: SessionDraft, seams?: SessionReadSeams): SessionRecord;
+/**
+ * Changes the stored record of a session, reading it again first, and
+ * answers the record written; a change's `appendStep` goes after the
+ * stored steps. Throws {@link SessionRecordError} when the
+ * record cannot be read or the change would make it one that cannot be,
+ * and {@link SessionStateError} when it stores a state the change's
+ * `onlyFrom` leaves out.
+ */
+export declare function updateSession(root: string, sessionId: string, change: SessionChange): SessionRecord;

package/dist/core/loop/suite-failure.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The record of one failing test, as `src/suite/run.ts` reads it from a
+ * JUnit report and a session record keeps it among a suite step's
+ * failures (`sessions.ts`).
+ *
+ * It sits in core so `sessions.ts` reads it without importing above
+ * core; `src/suite/run.ts` re-exports it under the same name.
+ */
+/** One failing test: its file, relative to the run's directory, and its full name. */
+export interface SuiteFailure {
+    readonly file: string;
+    /** Its describe names, outermost first, and its own, joined by ` > `. */
+    readonly name: string;
+    /**
+     * The first line of its JUnit failure's message; absent when the
+     * report gave none. Compared by `src/triage/inherited.ts` when present to
+     * identify inherited failures.
+     */
+    readonly message?: string;
+    /**
+     * The first lines of the error Bun printed for it on stderr, trimmed;
+     * absent when it printed none. See the module note of `src/suite/run.ts`.
+     */
+    readonly errorLines?: readonly string[];
+}

package/dist/core/output/active.d.ts

@@ -0,0 +1,100 @@
+/**
+ * The Output this process writes through, and the mode it renders in.
+ *
+ * A function that prints asks {@link activeOutput} for the output rather
+ * than taking one as an argument, as `src/start/stamp.ts` holds a run's
+ * plan stub: an `Output` threaded through every function that prints
+ * would add an argument to call sites that have nothing to say about
+ * output. The output is held in two places, and the readers answer the
+ * first that has one.
+ *
+ * ## The scope
+ *
+ * {@link runWithActiveOutput} runs a function with an output and a mode
+ * in an async scope of its own, an `AsyncLocalStorage`
+ * (`node:async_hooks`). Inside that function, and in everything it
+ * awaits or starts, the readers answer that output and that mode; once
+ * the function ends, however it ends, nothing of them is left. The
+ * dispatcher runs every command this way (`src/cli/dispatch.ts`), with
+ * the command's context output in the invocation's mode.
+ *
+ * A scope belongs to one run, so runs need not nest to stay apart. Two
+ * runs that overlap in one process, started together and awaited with
+ * `Promise.all`, each write through their own output whichever ends
+ * first. A run started inside another reads the inner output inside and
+ * the outer one after. The module-level value below keeps overlapping
+ * runs apart only while they nest: set and put back in a `finally` it is
+ * a stack, and two that end out of order leave the output of one of them
+ * for the rest of the process (#927).
+ *
+ * ## The module-level value
+ *
+ * Outside every scope the readers answer one module-level value, which
+ * no module but a test and its fixtures sets. Until one sets another, it
+ * is the `text` adapter at verbosity 0 writing to `process.stdout`.
+ * {@link setActiveOutput} with `null` puts that default back. The
+ * default is made once, when this module is first imported, so
+ * {@link activeOutput} answers the same object on every read while
+ * nothing is set. It holds `process.stdout` itself and calls its `write`
+ * on each line, so a spy set on `process.stdout.write` after the import
+ * sees every line.
+ *
+ * ## A set made inside a scope
+ *
+ * The readers prefer the scope, and {@link setActiveOutput} writes the
+ * module-level value alone, inside a scope as outside one. So a set made
+ * inside a scope changes nothing that scope reads, and is what the
+ * readers answer once the scope has ended. A scope's output cannot be
+ * replaced from inside it.
+ *
+ * ## What reads outside the scope
+ *
+ * A scope follows the awaits and the callbacks started inside it. A
+ * callback the runtime calls from elsewhere does not carry it. Measured
+ * under bun 1.3.14, three listeners registered inside a scope read no
+ * store: a `process.on` signal listener when the signal arrived, an
+ * abort listener that handler fired, and an abort listener an
+ * `AbortSignal.timeout` fired. A timer, a child process's `data`
+ * listener, a `readline` `line` listener and the code after an await
+ * such a handler settled all read the scope's. A reader outside the
+ * scope writes through the module-level value; one that needs the
+ * scope's output reads it where the listener is registered, or is
+ * wrapped with `AsyncResource.bind` there.
+ *
+ * ## The mode
+ *
+ * An Output carries no mode of its own, and two writers need one, so the
+ * mode is held beside the output, in the scope and at module level
+ * alike. `core/loop/claude.ts` echoes a session's stdout as the bytes it
+ * wrote in `text` mode and as one `log` event per line in `json` mode.
+ * `start/dispatch.ts` emits a `step` event per task in `json` mode
+ * alone, where the `text` adapter would render it as a `step: ` line
+ * beside the line announcing the task. The dispatcher hands each
+ * invocation's mode to its scope with its output. The default, and an
+ * output set at module level with no mode, render in `text`.
+ *
+ * Bun runs every test file in one process, and the module-level value is
+ * module state: a case that sets an output sets `null` after it, or each
+ * file bun runs later writes through that case's output, in that case's
+ * mode.
+ */
+import type { Output } from '../../ports/index.js';
+import type { OutputMode } from '../config/config-sections.js';
+/**
+ * Runs `run` with `output` as the active output, rendering in `mode`, in
+ * an async scope of its own, and answers what `run` answers. Both are
+ * read inside `run` and whatever it awaits, and nowhere after it; see
+ * the module note.
+ */
+export declare function runWithActiveOutput<T>(output: Output, mode: OutputMode, run: () => T): T;
+/**
+ * Sets the module-level output and the mode it renders in, `text`
+ * unless one is named. `null` puts the default back, in `text` whatever
+ * mode is named. Inside a scope it changes nothing that scope reads; see
+ * the module note.
+ */
+export declare function setActiveOutput(output: Output | null, mode?: OutputMode): void;
+/** The output to write through: the one of the scope this is read in, else the module-level one. */
+export declare function activeOutput(): Output;
+/** The mode the active output renders in, read as {@link activeOutput} is; see the module note. */
+export declare function activeOutputMode(): OutputMode;

package/dist/core/output/stream.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Where an Output adapter writes.
+ *
+ * Copied from open-tomato's `packages/shared/cli-core/src/output.ts`,
+ * where it is named `CliOutputStream`, at commit
+ * `18f94c843fff1bce65ed2245f8712ed9b64a2d51` (2026-06-25). Every output
+ * adapter writes through it, `text.ts` beside this module and `json.ts`
+ * and `events.ts` under `src/adapters/output/`, so it lives in none of
+ * them.
+ *
+ * The source spells `write` as a method. It is a function-typed property
+ * here, as every port function is in `packages/rafa/src/ports/index.ts`, whose note
+ * gives the reason. `process.stdout` is assignable to it, which
+ * `src/adapter-registry.ts` relies on when a context names no stream.
+ */
+/** A stream an Output adapter writes whole lines to. */
+export interface OutputStream {
+    /** Writes one chunk. What it answers is never read. */
+    write: (chunk: string) => unknown;
+}