@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/domains/session/retry.ts

@@ -0,0 +1,238 @@
+/**
+ * Retry settings and countdown helper (Phase 12 / Phase 22 seam).
+ *
+ * pi-agent-core surfaces provider failures as a terminal assistant message
+ * with `stopReason: "error"` + `errorMessage: <provider text>`. It does not
+ * schedule retries itself; application wrappers decide whether to treat the
+ * error as transient, wait, and call `agent.continue()`. pi-mono's
+ * coding-agent implements that in `core/agent-session.ts` via an exponential
+ * backoff, a countdown UI, and an abort handle.
+ *
+ * This module is the pure building block for the Clio equivalent. It:
+ *   1. Declares the RetrySettings shape and sensible defaults.
+ *   2. Exposes a deterministic heuristic (`isRetryableErrorMessage`) that
+ *      matches the transient error strings pi-ai providers actually emit.
+ *   3. Computes the backoff delay for a given attempt (`computeRetryDelayMs`)
+ *      with the cap the settings declare; callers schedule the wait.
+ *   4. Provides `createRetryCountdown` so the TUI can show seconds remaining
+ *      and cancel a pending retry on `Esc` without coupling to a specific
+ *      timer abstraction.
+ *
+ * No I/O, no pi-agent-core/pi-ai imports. The chat-loop wiring (which decides
+ * whether an agent_end with stopReason "error" triggers a retry) lives in
+ * `src/interactive/chat-loop.ts` and consumes this module; keeping the two
+ * split so the countdown can be exercised in unit tests without spinning up a
+ * runtime.
+ */
+
+import { performance } from "node:perf_hooks";
+import type { RetrySettings } from "../../core/defaults.js";
+
+export type { RetrySettings } from "../../core/defaults.js";
+
+/**
+ * User-facing retry configuration lives in core defaults so settings and the
+ * session retry helper share one structural type.
+ */
+export const DEFAULT_RETRY_SETTINGS: RetrySettings = {
+	enabled: true,
+	maxRetries: 3,
+	baseDelayMs: 2000,
+	maxDelayMs: 60000,
+	streamStallMs: 180000,
+};
+
+/**
+ * Pattern list built from pi-mono's `_isRetryableError` regex (agent-session.ts).
+ * Kept as a plain RegExp so the check is `O(1)` per assistant error message.
+ * The match is case-insensitive: providers phrase the same error in mixed
+ * case (Anthropic: "Overloaded", OpenRouter: "rate limited", Fireworks:
+ * "connection error"), and we want all of them classified as transient.
+ */
+const RETRYABLE_PATTERN =
+	/overloaded|provider.?returned.?error|rate.?limit|too many requests|429|500|502|503|504|service.?unavailable|server.?error|internal.?error|network.?error|connection.?error|connection.?refused|connection.?lost|other side closed|fetch failed|upstream.?connect|reset before headers|socket hang up|ended without|timed? out|timeout|terminated|retry delay/i;
+
+/**
+ * A self-hosted server refusing a request because the model is not resident.
+ *
+ * Measured against LM Studio, which answers a request for an evicted model
+ * with `500 Internal Server Error` on the first attempt and the bare string
+ * `Model is unloaded.` on the next, while it loads. llama.cpp behind
+ * llama-swap and Ollama phrase the same condition differently, so the pattern
+ * covers the family rather than one vendor's wording.
+ *
+ * Deliberately not folded into {@link RETRYABLE_PATTERN}: this is transient in
+ * a different unit. A rate limit clears in a second or two; a 35B model loads
+ * off disk in twenty to sixty, and retrying it on a rate limit's backoff burns
+ * every attempt before the server is ready. `clio-coder run --target node-a --model
+ * example-coder-model` failed exactly this way: two attempts, six
+ * seconds, "Model is unloaded." on stdout, while the load was still running.
+ */
+const MODEL_LOADING_PATTERN =
+	/model is unloaded|model is (?:still )?loading|model not loaded|no model (?:is )?loaded|loading model|model_?load(?:ing)?_?in_?progress|is not loaded/i;
+
+/** Floor for a retry that is waiting on a model load rather than on a provider. */
+const MODEL_LOADING_MIN_DELAY_MS = 15000;
+
+/**
+ * True when the error says the target is loading the model, so the wait should
+ * be sized for disk and VRAM rather than for a provider backing off.
+ */
+export function isModelLoadingErrorMessage(errorMessage: string | null | undefined): boolean {
+	if (!errorMessage || errorMessage.length === 0) return false;
+	return MODEL_LOADING_PATTERN.test(errorMessage);
+}
+
+/**
+ * True when an error message looks like a transient failure worth retrying:
+ * a provider backing off, or a self-hosted target loading the model.
+ * Context-overflow errors are intentionally excluded: those route through
+ * compaction + one-shot recovery, not this retry loop.
+ *
+ * Callers pass `assistantMessage.errorMessage` directly; an empty string
+ * returns false so a missing provider error never triggers an unnecessary
+ * retry.
+ */
+export function isRetryableErrorMessage(errorMessage: string | null | undefined): boolean {
+	if (!errorMessage || errorMessage.length === 0) return false;
+	return RETRYABLE_PATTERN.test(errorMessage) || MODEL_LOADING_PATTERN.test(errorMessage);
+}
+
+/**
+ * Compute the delay before attempt `attempt` (1-indexed). Matches pi-mono's
+ * formula `baseDelayMs * 2 ** (attempt - 1)`, then clamps to `maxDelayMs` so
+ * the 4th retry never stalls for minutes. Attempt < 1 is normalized to 1 so
+ * callers that miscount still get a sane first delay.
+ */
+export function computeRetryDelayMs(
+	attempt: number,
+	settings: RetrySettings = DEFAULT_RETRY_SETTINGS,
+	errorMessage?: string | null,
+): number {
+	const safeAttempt = Math.max(1, Math.floor(attempt));
+	const raw = settings.baseDelayMs * 2 ** (safeAttempt - 1);
+	const base =
+		!Number.isFinite(raw) || raw <= 0 ? Math.max(0, settings.baseDelayMs) : Math.min(raw, settings.maxDelayMs);
+	// A model load does not finish faster because the retry schedule was
+	// written for a rate limit. `maxDelayMs` still caps it, so an operator who
+	// wants short waits keeps them.
+	if (!isModelLoadingErrorMessage(errorMessage)) return base;
+	return Math.min(Math.max(base, MODEL_LOADING_MIN_DELAY_MS), settings.maxDelayMs);
+}
+
+/**
+ * Runtime state for a single retry wait. `seconds` counts down from the
+ * initial delay; `done` flips true when the deadline is reached; `cancelled`
+ * flips true when a caller aborts via `cancel()` before the deadline.
+ */
+export interface RetryCountdownState {
+	attempt: number;
+	maxAttempts: number;
+	seconds: number;
+	done: boolean;
+	cancelled: boolean;
+}
+
+export interface RetryCountdownOptions {
+	/** 1-indexed attempt id displayed to the user, e.g. "Retrying (1/3)". */
+	attempt: number;
+	/** Upper bound displayed alongside `attempt`. */
+	maxAttempts: number;
+	/** Total wait in milliseconds. Callers usually pass `computeRetryDelayMs(attempt, settings)`. */
+	delayMs: number;
+	/** Fires on every tick with the latest state so the TUI can redraw. */
+	onTick: (state: RetryCountdownState) => void;
+	/** Fires once when the countdown reaches zero naturally. */
+	onDone: () => void;
+	/** Fires once when `cancel()` runs before the deadline. */
+	onCancel?: () => void;
+	/**
+	 * Schedule a callback after `ms` milliseconds. Defaults to `setTimeout`.
+	 * Tests swap this for a deterministic clock so the countdown advances
+	 * without wall-clock waits.
+	 */
+	setTimer?: (cb: () => void, ms: number) => unknown;
+	/** Mirror of `clearTimeout`. Paired with `setTimer`. */
+	clearTimer?: (id: unknown) => void;
+	/**
+	 * Monotonic millisecond source for the countdown. Defaults to
+	 * `performance.now`: the remaining wait is a span, so a clock correction
+	 * mid-countdown must not shorten or extend it.
+	 */
+	now?: () => number;
+}
+
+export interface RetryCountdownHandle {
+	/** Latest state snapshot. Useful for tests that inspect without subscribing. */
+	getState(): RetryCountdownState;
+	/** Abort the countdown before the deadline; fires `onCancel` if registered. */
+	cancel(): void;
+}
+
+/**
+ * One-second-resolution countdown loop that drives a TUI retry indicator.
+ * The first `onTick` fires synchronously so the caller can paint an initial
+ * frame without waiting a whole second; subsequent ticks fire every 1000ms
+ * until the deadline is reached or `cancel()` is called. All state lives in
+ * the returned handle; the function itself has no module-level mutable
+ * state, which keeps parallel retry counters safe under concurrent tests.
+ */
+export function createRetryCountdown(options: RetryCountdownOptions): RetryCountdownHandle {
+	const setTimer = options.setTimer ?? ((cb, ms) => setTimeout(cb, ms));
+	const clearTimer = options.clearTimer ?? ((id) => clearTimeout(id as ReturnType<typeof setTimeout>));
+	const now = options.now ?? (() => performance.now());
+
+	const start = now();
+	const deadline = start + Math.max(0, options.delayMs);
+
+	const state: RetryCountdownState = {
+		attempt: options.attempt,
+		maxAttempts: options.maxAttempts,
+		seconds: Math.max(0, Math.ceil(options.delayMs / 1000)),
+		done: false,
+		cancelled: false,
+	};
+
+	let timer: unknown = null;
+	let settled = false;
+
+	const emit = (): void => {
+		options.onTick({ ...state });
+	};
+
+	const schedule = (): void => {
+		if (settled) return;
+		const remaining = deadline - now();
+		if (remaining <= 0) {
+			state.seconds = 0;
+			state.done = true;
+			settled = true;
+			emit();
+			options.onDone();
+			return;
+		}
+		state.seconds = Math.max(0, Math.ceil(remaining / 1000));
+		emit();
+		timer = setTimer(schedule, 1000);
+	};
+
+	schedule();
+
+	return {
+		getState() {
+			return { ...state };
+		},
+		cancel() {
+			if (settled) return;
+			settled = true;
+			if (timer !== null) {
+				clearTimer(timer);
+				timer = null;
+			}
+			state.cancelled = true;
+			state.seconds = 0;
+			emit();
+			options.onCancel?.();
+		},
+	};
+}

package/src/domains/session/task-board.ts

@@ -0,0 +1,375 @@
+import type { SessionEntry, TaskLedgerGoal, TaskLedgerStatus, TaskLedgerValidationEvidence } from "./entries.js";
+
+/**
+ * The session task board: the live state behind the `tasks` tool, the footer
+ * tasks row, and the /tasks overlay. Every mutation persists a full-snapshot
+ * `taskLedger` entry (the dormant Phase 12 entry kind gains its producer
+ * here), so the board is replayable from the JSONL alone and survives
+ * resume/fork without any side-car state.
+ *
+ * Shape mapping onto TaskLedgerEntry:
+ *   - the board title is the single top-level goal
+ *   - tasks are subgoals with parentGoalId pointing at that goal
+ *   - a completion note becomes a passed requiredValidationEvidence row,
+ *     so "done" carries its receipt instead of a bare status flip
+ */
+
+const TASK_BOARD_GOAL_ID = "board";
+
+export interface TaskBoardTask {
+	id: string;
+	title: string;
+	status: TaskLedgerStatus;
+	/** Block or drop reason; empty for pending/active/completed tasks. */
+	reason?: string;
+	/** Evidence note recorded when the task was completed. */
+	evidence?: string;
+}
+
+export interface TaskBoardSnapshot {
+	title: string;
+	tasks: ReadonlyArray<TaskBoardTask>;
+	/**
+	 * Dispatch runs currently in flight while this board is live, attached by
+	 * the orchestrator from the dispatch bus. Process-local linkage: it is
+	 * persisted on every snapshot so the JSONL records which runs served the
+	 * board, but a refold after resume/fork restores it empty because those
+	 * runs belong to the process that dispatched them.
+	 */
+	activeRunIds: ReadonlyArray<string>;
+}
+
+export interface TaskBoardCounts {
+	total: number;
+	completed: number;
+	active: number;
+	pending: number;
+	blocked: number;
+	cancelled: number;
+	/** Tasks still owed work: pending + active. */
+	open: number;
+}
+
+export type TaskBoardMutation =
+	| { op: "plan"; title: string; tasks: ReadonlyArray<string> }
+	| { op: "add"; tasks: ReadonlyArray<string> }
+	| { op: "start"; id: string }
+	| { op: "done"; id: string; evidence: string }
+	| { op: "block"; id: string; reason: string }
+	| { op: "drop"; id: string; reason?: string };
+
+export type TaskBoardMutationResult =
+	| { ok: true; board: TaskBoardSnapshot; notes: ReadonlyArray<string> }
+	| { ok: false; message: string };
+
+/**
+ * The fields a `taskLedger` entry carries beyond the BaseSessionEntry
+ * envelope. `appendEntry` fills turnId/timestamp; parentTurnId stays null
+ * because ledger snapshots are side-car bookkeeping (like label entries)
+ * that never project into tree.json.
+ */
+export interface TaskLedgerEntryFields {
+	kind: "taskLedger";
+	parentTurnId: null;
+	goals: TaskLedgerGoal[];
+	subgoals: TaskLedgerGoal[];
+	activeRunIds: string[];
+	requiredValidationEvidence: TaskLedgerValidationEvidence[];
+}
+
+export interface TaskBoardStoreDeps {
+	/**
+	 * Current session id, or null when no session is bound. The store keys its
+	 * in-memory board on this: a resume/fork/new-session switch invalidates the
+	 * cache and the next read refolds the board from the session's entries.
+	 */
+	getSessionId?: () => string | null;
+	/** Session entries for refolding after a session switch. */
+	readEntries?: () => ReadonlyArray<unknown>;
+	/** Persist one full-snapshot taskLedger entry. Absent means in-memory only. */
+	appendEntry?: (entry: TaskLedgerEntryFields) => void;
+	now?: () => Date;
+}
+
+export interface TaskBoardStore {
+	/** Current board, refolded from the session ledger after a session switch. */
+	snapshot(): TaskBoardSnapshot | null;
+	/** Apply one mutation, persist the resulting snapshot, and return it. */
+	apply(mutation: TaskBoardMutation): TaskBoardMutationResult;
+	/** Link an in-flight dispatch run to the board; a no-op without a board. */
+	attachRun(runId: string): void;
+	/** Unlink a finished dispatch run; a no-op when it was never attached. */
+	detachRun(runId: string): void;
+}
+
+export function taskBoardCounts(board: Pick<TaskBoardSnapshot, "tasks">): TaskBoardCounts {
+	const counts: TaskBoardCounts = {
+		total: board.tasks.length,
+		completed: 0,
+		active: 0,
+		pending: 0,
+		blocked: 0,
+		cancelled: 0,
+		open: 0,
+	};
+	for (const task of board.tasks) {
+		if (task.status === "completed") counts.completed += 1;
+		else if (task.status === "active") counts.active += 1;
+		else if (task.status === "pending") counts.pending += 1;
+		else if (task.status === "blocked") counts.blocked += 1;
+		else counts.cancelled += 1;
+	}
+	counts.open = counts.pending + counts.active;
+	return counts;
+}
+
+/** Board status for the ledger's top-level goal, derived from its tasks. */
+function boardStatus(tasks: ReadonlyArray<TaskBoardTask>): TaskLedgerStatus {
+	const counts = taskBoardCounts({ tasks });
+	if (counts.total === 0) return "pending";
+	if (counts.active > 0) return "active";
+	if (counts.open === 0 && counts.blocked === 0) return "completed";
+	if (counts.blocked > 0 && counts.open === 0) return "blocked";
+	return "pending";
+}
+
+export function toTaskLedgerEntryFields(board: TaskBoardSnapshot, now: Date): TaskLedgerEntryFields {
+	const evidence: TaskLedgerValidationEvidence[] = [];
+	const subgoals: TaskLedgerGoal[] = board.tasks.map((task) => {
+		if (task.status === "completed" && task.evidence) {
+			evidence.push({
+				id: `${task.id}.evidence`,
+				description: task.evidence,
+				status: "passed",
+				observedAt: now.toISOString(),
+			});
+		}
+		const goal: TaskLedgerGoal = {
+			id: task.id,
+			title: task.title,
+			status: task.status,
+			parentGoalId: TASK_BOARD_GOAL_ID,
+		};
+		if (task.reason) goal.description = task.reason;
+		return goal;
+	});
+	return {
+		kind: "taskLedger",
+		parentTurnId: null,
+		goals: [{ id: TASK_BOARD_GOAL_ID, title: board.title, status: boardStatus(board.tasks) }],
+		subgoals,
+		activeRunIds: [...board.activeRunIds],
+		requiredValidationEvidence: evidence,
+	};
+}
+
+function isTaskLedgerShaped(value: unknown): value is {
+	kind: "taskLedger";
+	goals: TaskLedgerGoal[];
+	subgoals: TaskLedgerGoal[];
+	requiredValidationEvidence: TaskLedgerValidationEvidence[];
+} {
+	if (!value || typeof value !== "object") return false;
+	const entry = value as Partial<SessionEntry>;
+	return entry.kind === "taskLedger" && Array.isArray((entry as { goals?: unknown }).goals);
+}
+
+/**
+ * Fold a session's entries back into a board. Each taskLedger entry is a full
+ * snapshot, so the last one wins; earlier entries are history, not deltas.
+ */
+export function foldTaskBoard(entries: ReadonlyArray<unknown>): TaskBoardSnapshot | null {
+	let last: ReturnType<typeof toEntryView> = null;
+	for (const raw of entries) {
+		if (isTaskLedgerShaped(raw)) last = toEntryView(raw);
+	}
+	return last;
+}
+
+function toEntryView(entry: {
+	goals: TaskLedgerGoal[];
+	subgoals: TaskLedgerGoal[];
+	requiredValidationEvidence: TaskLedgerValidationEvidence[];
+}): TaskBoardSnapshot | null {
+	const boardGoal = entry.goals[0];
+	if (!boardGoal) return null;
+	const evidenceByTask = new Map<string, string>();
+	for (const item of entry.requiredValidationEvidence) {
+		const taskId = item.id.endsWith(".evidence") ? item.id.slice(0, -".evidence".length) : item.id;
+		evidenceByTask.set(taskId, item.description);
+	}
+	return {
+		title: boardGoal.title,
+		tasks: entry.subgoals.map((goal) => {
+			const task: TaskBoardTask = { id: goal.id, title: goal.title, status: goal.status };
+			if (goal.description) task.reason = goal.description;
+			const evidence = evidenceByTask.get(goal.id);
+			if (evidence) task.evidence = evidence;
+			return task;
+		}),
+		// Run linkage is process-live: the runs recorded in old entries ended
+		// with the process that dispatched them, so a refold starts empty and
+		// the historical linkage stays readable in the earlier entries.
+		activeRunIds: [],
+	};
+}
+
+function nextTaskId(tasks: ReadonlyArray<TaskBoardTask>): number {
+	let max = 0;
+	for (const task of tasks) {
+		const match = /^t(\d+)$/.exec(task.id);
+		if (match) max = Math.max(max, Number(match[1]));
+	}
+	return max + 1;
+}
+
+function normalizeTitles(titles: ReadonlyArray<string>): string[] {
+	return titles.map((title) => title.trim()).filter((title) => title.length > 0);
+}
+
+function applyMutation(
+	board: TaskBoardSnapshot | null,
+	mutation: TaskBoardMutation,
+): { board: TaskBoardSnapshot; notes: string[] } | { error: string } {
+	if (mutation.op === "plan") {
+		const titles = normalizeTitles(mutation.tasks);
+		if (mutation.title.trim().length === 0) return { error: "plan requires a non-empty title" };
+		if (titles.length === 0) return { error: "plan requires at least one task" };
+		const notes: string[] = [];
+		if (board && taskBoardCounts(board).open > 0) {
+			notes.push(`replaced board "${board.title}" with ${taskBoardCounts(board).open} task(s) still open`);
+		}
+		return {
+			board: {
+				title: mutation.title.trim(),
+				tasks: titles.map((title, index) => ({ id: `t${index + 1}`, title, status: "pending" as const })),
+				// Runs in flight outlive a board swap: they belong to the session,
+				// so the fresh board inherits the linkage until the runs finish.
+				activeRunIds: board?.activeRunIds ?? [],
+			},
+			notes,
+		};
+	}
+	if (board === null) return { error: 'no task board yet; declare one with action="plan" first' };
+	if (mutation.op === "add") {
+		const titles = normalizeTitles(mutation.tasks);
+		if (titles.length === 0) return { error: "add requires at least one task" };
+		const start = nextTaskId(board.tasks);
+		const added = titles.map((title, index) => ({ id: `t${start + index}`, title, status: "pending" as const }));
+		return { board: { ...board, tasks: [...board.tasks, ...added] }, notes: [] };
+	}
+	const target = board.tasks.find((task) => task.id === mutation.id);
+	if (!target) return { error: `task ${mutation.id} not found on the board` };
+	if (mutation.op === "block" && mutation.reason.trim().length === 0) {
+		return { error: "block requires a reason so the ledger records why work stopped" };
+	}
+	// Completion is the ledger's only load-bearing claim, so it carries two
+	// structural conditions rather than a bare status flip. Evidence is
+	// mandatory: a completed row becomes a passed validation record, and a row
+	// without evidence would assert a validation that nobody performed. The
+	// task must also have been started, because work that was never entered
+	// cannot have produced a result; the honest closes for it are block and
+	// drop, which record a reason instead.
+	if (mutation.op === "done") {
+		if (mutation.evidence.trim().length === 0) {
+			return {
+				error:
+					"done requires note as the evidence that the task actually finished (the command you ran, the file:line you verified). If the work did not happen, use block with a reason or drop it.",
+			};
+		}
+		if (target.status === "pending") {
+			return {
+				error: `task ${target.id} was never started, so it cannot be completed. Start it and do the work, or record the truth with block (reason) or drop.`,
+			};
+		}
+	}
+	const notes: string[] = [];
+	const tasks = board.tasks.map((task): TaskBoardTask => {
+		if (task.id !== target.id) {
+			// One active task at a time: starting a task parks any other active
+			// task back to pending so the board always names the current focus.
+			if (mutation.op === "start" && task.status === "active") {
+				notes.push(`parked ${task.id} back to pending (one task active at a time)`);
+				return { ...task, status: "pending" };
+			}
+			return task;
+		}
+		return applyStatusMutation(task, mutation);
+	});
+	return { board: { ...board, tasks }, notes };
+}
+
+function applyStatusMutation(
+	task: TaskBoardTask,
+	mutation: Extract<TaskBoardMutation, { op: "start" | "done" | "block" | "drop" }>,
+): TaskBoardTask {
+	switch (mutation.op) {
+		case "start":
+			return { ...task, status: "active" };
+		case "done": {
+			const done: TaskBoardTask = { ...task, status: "completed", evidence: mutation.evidence.trim() };
+			delete done.reason;
+			return done;
+		}
+		case "block":
+			return { ...task, status: "blocked", reason: mutation.reason.trim() };
+		case "drop": {
+			const dropped: TaskBoardTask = { ...task, status: "cancelled" };
+			if (mutation.reason?.trim()) dropped.reason = mutation.reason.trim();
+			return dropped;
+		}
+	}
+}
+
+export function createTaskBoardStore(deps: TaskBoardStoreDeps = {}): TaskBoardStore {
+	let cachedSessionId: string | null | undefined;
+	let board: TaskBoardSnapshot | null = null;
+
+	const syncToSession = (): void => {
+		const sessionId = deps.getSessionId?.() ?? null;
+		if (cachedSessionId === sessionId) return;
+		cachedSessionId = sessionId;
+		try {
+			board = deps.readEntries ? foldTaskBoard(deps.readEntries()) : null;
+		} catch {
+			board = null;
+		}
+	};
+
+	const persist = (next: TaskBoardSnapshot): void => {
+		try {
+			deps.appendEntry?.(toTaskLedgerEntryFields(next, deps.now?.() ?? new Date()));
+		} catch {
+			// Persistence is best-effort: the live board still drives the UI
+			// and the model; a failed ledger write only costs replay fidelity.
+		}
+	};
+
+	return {
+		snapshot(): TaskBoardSnapshot | null {
+			syncToSession();
+			return board;
+		},
+		apply(mutation: TaskBoardMutation): TaskBoardMutationResult {
+			syncToSession();
+			const result = applyMutation(board, mutation);
+			if ("error" in result) return { ok: false, message: result.error };
+			board = result.board;
+			persist(result.board);
+			return { ok: true, board: result.board, notes: result.notes };
+		},
+		attachRun(runId: string): void {
+			syncToSession();
+			// A run can only link to a live board; without one, nothing tracks it.
+			if (board === null || runId.length === 0 || board.activeRunIds.includes(runId)) return;
+			board = { ...board, activeRunIds: [...board.activeRunIds, runId] };
+			persist(board);
+		},
+		detachRun(runId: string): void {
+			syncToSession();
+			if (board === null || !board.activeRunIds.includes(runId)) return;
+			board = { ...board, activeRunIds: board.activeRunIds.filter((id) => id !== runId) };
+			persist(board);
+		},
+	};
+}