@hicaru/pi-rlm 0.2.1 → 0.2.2

package/src/core/pipeline.ts

@@ -1,268 +0,0 @@
-/**
- * RLM pipeline stage graph — data-driven transitions with deterministic gates.
- *
- * Stages: clarify → research → blueprint → validate
- * (clarify skipped when askUserQuestion is off).
- * The root RLM writes artifacts via save_artifact(); advance_phase() is gated by
- * TypeScript floors (never LLM judgment). Validate routes on measured
- * blockers_count with a bounded corrective loop back to blueprint.
- * The pipeline is read-only by design: it produces a validated plan and does not
- * write source. Accidental sandbox writes are blocked (open/pathlib/os.open);
- * this is steering, not a hard security boundary.
- */
-import {
-  checkStatusReady,
-  clarificationRecord,
-  type ClarificationGateData,
-  type GateResult,
-  planPhaseRecords,
-  type PlanGateData,
-  type ValidationGateData,
-  validationRecord,
-  verifyCitations,
-} from "./gates.ts";
-
-export type Phase = "clarify" | "research" | "blueprint" | "validate";
-
-export const PHASES = Object.freeze([
-  "clarify",
-  "research",
-  "blueprint",
-  "validate",
-] as const satisfies readonly Phase[]);
-
-const PHASE_SET: ReadonlySet<string> = Object.freeze(new Set<string>(PHASES));
-
-export function isPhase(value: unknown): value is Phase {
-  return typeof value === "string" && PHASE_SET.has(value);
-}
-
-/**
- * Map a persisted phase name onto the current graph. Trails written before the
- * implement phase was retired resume at `blueprint` — the last phase whose
- * artifact is still meaningful.
- */
-export function reconcilePhase(persisted: unknown): Phase {
-  if (isPhase(persisted)) return persisted;
-  return "blueprint";
-}
-
-/** Kind string the model passes to save_artifact(kind, content). */
-export type ArtifactKind = "clarification" | "research" | "plan" | "validation";
-
-/** Structured data a stage gate extracts from its artifact (what edges route on). */
-export type StageGateData =
-  | { readonly kind: "clarification"; readonly clarification: ClarificationGateData }
-  | { readonly kind: "research" }
-  | { readonly kind: "plan"; readonly plan: PlanGateData }
-  | { readonly kind: "validation"; readonly validation: ValidationGateData };
-
-export interface StageDef {
-  readonly phase: Phase;
-  /** Subdir under .rlm/artifacts/ ("" = side-effect stage, no artifact). */
-  readonly artifactDir: string;
-  /** save_artifact kind, or "" when the stage produces no artifact. */
-  readonly artifactKind: ArtifactKind | "";
-  /** Deterministic floor run on the artifact BEFORE leaving this stage. */
-  readonly gate: (content: string, path: string, cwd: string) => GateResult<StageGateData>;
-}
-
-const clarifyGate: StageDef["gate"] = (content, path) => {
-  const status = checkStatusReady(content, path);
-  if (!status.ok) return status;
-  const rec = clarificationRecord(content, path);
-  if (!rec.ok) return rec;
-  return { ok: true, value: { kind: "clarification", clarification: rec.value } };
-};
-
-/** Compose floors: status: ready → citations → stage-specific contract. */
-const researchGate: StageDef["gate"] = (content, path, cwd) => {
-  const status = checkStatusReady(content, path);
-  if (!status.ok) return status;
-  const cites = verifyCitations(content, cwd);
-  if (!cites.ok) return cites;
-  return { ok: true, value: { kind: "research" } };
-};
-
-const blueprintGate: StageDef["gate"] = (content, path, cwd) => {
-  const status = checkStatusReady(content, path);
-  if (!status.ok) return status;
-  const cites = verifyCitations(content, cwd);
-  if (!cites.ok) return cites;
-  const plan = planPhaseRecords(content, path);
-  if (!plan.ok) return plan;
-  return { ok: true, value: { kind: "plan", plan: plan.value } };
-};
-
-const validateGate: StageDef["gate"] = (content, path) => {
-  const status = checkStatusReady(content, path);
-  if (!status.ok) return status;
-  const rec = validationRecord(content, path);
-  if (!rec.ok) return rec;
-  return { ok: true, value: { kind: "validation", validation: rec.value } };
-};
-
-/** Single source of truth for gates, artifact dirs/kinds, and routing. */
-export const STAGES: Readonly<Record<Phase, StageDef>> = Object.freeze({
-  clarify: { phase: "clarify", artifactDir: "clarifications", artifactKind: "clarification", gate: clarifyGate },
-  research: { phase: "research", artifactDir: "research", artifactKind: "research", gate: researchGate },
-  blueprint: { phase: "blueprint", artifactDir: "plans", artifactKind: "plan", gate: blueprintGate },
-  validate: { phase: "validate", artifactDir: "validations", artifactKind: "validation", gate: validateGate },
-});
-
-/** Lookup stage by save_artifact kind — single map derived from STAGES (DRY). */
-const STAGE_BY_KIND: Readonly<Partial<Record<ArtifactKind, StageDef>>> = Object.freeze(
-  (Object.values(STAGES) as readonly StageDef[]).reduce<Partial<Record<ArtifactKind, StageDef>>>((acc, stage) => {
-    if (stage.artifactKind !== "") acc[stage.artifactKind] = stage;
-    return acc;
-  }, {}),
-);
-
-export function stageForArtifactKind(kind: string): StageDef | undefined {
-  if (kind === "clarification" || kind === "research" || kind === "plan" || kind === "validation") {
-    return STAGE_BY_KIND[kind];
-  }
-  return undefined;
-}
-
-/** An artifact path plus its lifecycle status — append-only, never deleted. */
-export interface ArtifactRef {
-  readonly path: string;
-  readonly status: "active" | "superseded";
-  /** Path of the artifact that superseded this one (the rejecting validation). */
-  readonly supersededBy?: string;
-}
-
-/** The latest artifact saved for a stage, plus its gate result when it passed. */
-export interface SavedArtifact {
-  readonly path: string;
-  /** Gate payload when the artifact passed; undefined ⇒ advance_phase must re-gate. */
-  readonly gateData?: StageGateData;
-}
-
-export interface PhaseState {
-  readonly current: Phase;
-  readonly advancedAt: number;
-  readonly summary?: string;
-  /** Artifact each completed stage produced — the named channels. */
-  readonly artifacts: Readonly<Partial<Record<Phase, ArtifactRef>>>;
-  /** Corrective validate→blueprint re-entries taken so far. */
-  readonly backwardJumps: number;
-}
-
-/**
- * @param start — first phase of the run (`clarify` when interviews are on, else `research`).
- */
-export function initialPhaseState(advancedAt = 0, start: Phase = "clarify"): PhaseState {
-  return { current: start, advancedAt, artifacts: Object.freeze({}), backwardJumps: 0 };
-}
-
-export type RouteDecision =
-  | { readonly kind: "done" }
-  | { readonly kind: "loop-back"; readonly next: "blueprint" }
-  | { readonly kind: "halt"; readonly reason: string };
-
-/**
- * Route out of `validate` on MEASURED gate data: blockers_count === 0 → done;
- * blockers_count > 0 → loop back to blueprint, bounded by maxBackwardJumps.
- */
-export function routeAfterValidate(
-  data: ValidationGateData,
-  backwardJumps: number,
-  maxBackwardJumps: number,
-): RouteDecision {
-  if (data.blockersCount === 0) return { kind: "done" };
-  if (backwardJumps >= maxBackwardJumps) {
-    return {
-      kind: "halt",
-      reason: `validation reports ${data.blockersCount} blocker(s) after ${backwardJumps} corrective pass(es) — backward-jump limit (${maxBackwardJumps}) reached; surfacing the validation report as the final answer`,
-    };
-  }
-  return { kind: "loop-back", next: "blueprint" };
-}
-
-/** Forward transitions only; corrective loop-back is ENGINE-initiated via routeAfterValidate. */
-export function nextForward(current: Phase): Phase | undefined {
-  const idx = PHASES.indexOf(current);
-  return idx >= 0 && idx < PHASES.length - 1 ? PHASES[idx + 1] : undefined;
-}
-
-export interface AdvancePhaseResult {
-  readonly ok: true;
-  readonly phase: Phase;
-}
-
-export interface AdvancePhaseFailure {
-  readonly ok: false;
-  readonly error: string;
-  readonly phase: Phase;
-}
-
-export type AdvancePhaseOutcome = AdvancePhaseResult | AdvancePhaseFailure;
-
-/**
- * Pure order check: only the immediate next phase is allowed.
- * Artifact gates are applied by the engine after this returns ok.
- */
-export function advancePhase(
-  current: Phase | undefined,
-  target: string,
-): AdvancePhaseOutcome {
-  if (!isPhase(target)) {
-    return {
-      ok: false,
-      error: `unknown phase '${target}'; valid phases: ${PHASES.join(", ")}`,
-      phase: current ?? PHASES[0],
-    };
-  }
-  const from = current ?? PHASES[0];
-  const expected = nextForward(from);
-  if (expected === undefined) {
-    return {
-      ok: false,
-      error: `'${from}' is the terminal phase; finalize via answer["ready"] = True after saving the validation artifact`,
-      phase: from,
-    };
-  }
-  if (target !== expected) {
-    return {
-      ok: false,
-      error: `cannot advance from '${from}' to '${target}' — the next phase is '${expected}'`,
-      phase: from,
-    };
-  }
-  return { ok: true, phase: target };
-}
-
-/** Return the current phase (defaults to first phase if undefined). */
-export function currentPhase(state: PhaseState | undefined): Phase {
-  return state?.current ?? PHASES[0];
-}
-
-/** Return the number of turns spent in the current phase. */
-export function turnsInPhase(state: PhaseState | undefined, completedTurns: number): number {
-  return state ? completedTurns - state.advancedAt : completedTurns;
-}
-
-/** PHASE_GATE_TURNS: if the model stays in one phase for this many turns, the engine re-prompts. */
-export const PHASE_GATE_TURNS = 4;
-
-/** Produce a re-prompt message when the model stalls in a phase for too long. */
-export function phaseGatePrompt(
-  state: PhaseState | undefined,
-  completedTurns: number,
-): string | undefined {
-  const turns = turnsInPhase(state, completedTurns);
-  const phase = currentPhase(state);
-  if (turns >= PHASE_GATE_TURNS && turns % PHASE_GATE_TURNS === 0) {
-    const next = nextForward(phase);
-    const hint = next
-      ? ` Consider calling advance_phase("${next}") if your ${phase} work is complete (after save_artifact when required).`
-      : "";
-    return [
-      `You have spent ${turns} turns in the '${phase}' phase.`,
-      `If the ${phase} phase is complete, advance to the next phase.${hint}`,
-    ].join(" ");
-  }
-  return undefined;
-}

package/src/prompts/phases.ts

@@ -1,104 +0,0 @@
-/**
- * Per-phase guidance for the gated RLM pipeline.
- * Injected at each phase boundary; the only channel between phases is durable
- * artifacts under .rlm/artifacts/.
- */
-import type { Phase } from "../core/pipeline.ts";
-
-const CLARIFY_GUIDANCE = Object.freeze([
-  "## Clarify phase (intake interview)",
-  "Interview the user until the task is understood. The engine COUNTS ask_user_question",
-  "rounds it services — you cannot advance without having actually asked at least once.",
-  "",
-  "1. Intent first: ask ONE open-ended intent question (what problem, who hits it, what",
-  "   success looks like). Options are answer *shapes* (e.g. end user / maintainer / operator);",
-  "   do NOT mark a Recommended option. The automatic Other / free-text path carries the real framing.",
-  "   Up to 2 more intent rounds if the answer still cannot scope a narrow probe; then proceed",
-  "   with what you have.",
-  "2. Probe before asking more: ground follow-ups in the REPL (deterministic search over",
-  "   context, a few llm_query reads) so questions cite real code as file:line.",
-  "3. Confirm inferences, don't record them: batch inferred decisions into one call —",
-  "   \"From the code I inferred <behavior> (file:line). Keep or change?\" The user's answer",
-  "   is the Decision, not your inference.",
-  "4. Scope / shape / detail rounds, one at a time: recommended option first; architecture",
-  "   (shape) options must state the tradeoff (\"optimizes X, costs Y\") — never one option",
-  "   masquerading as a choice; 2–4 independent detail questions may batch in one call.",
-  "5. Classify answers: Decision → record; Correction → re-probe that seam, re-ask dependents;",
-  "   Defer → ## Open Questions.",
-  "6. Terminate on depth, not politeness: stop when every raised branch has a Decision or a",
-  "   Deferral and ## Problem & Intent holds the user's own words verbatim. Do not pad the",
-  "   interview; do not ask a final \"looks good?\" rubber-stamp.",
-  "7. Then save_artifact(\"clarification\", content) with frontmatter:",
-  "     status: ready",
-  "     decisions_count: N",
-  "     open_questions_count: M",
-  "   and body sections:",
-  "     ## Problem & Intent  (user's words VERBATIM)",
-  "     ## Decisions         (one '- ' bullet per decision)",
-  "     ## Open Questions    (one '- ' bullet per deferral; may be empty with count 0)",
-  "     ## Non-Goals",
-  '   Then advance_phase("research", summary).',
-].join("\n"));
-
-const RESEARCH_GUIDANCE = Object.freeze([
-  "## Research phase",
-  "Read the clarifications artifact (if present) and honor recorded Decisions; do not silently",
-  "resolve Open Questions.",
-  "Probe the repository, delegate long reads via `llm_query_batched` / `llm_query_chunked`.",
-  "Every factual claim about the code MUST be cited as `path/file.ext:LINE` (or `LINE-LINE`).",
-  "The engine VERIFIES citations against the working tree — unbacked citations reject advance.",
-  "When research is complete, write ONE research document with a `## Findings` section and call:",
-  '  `save_artifact("research", content)`  # frontmatter must include `status: ready`',
-  '  `advance_phase("blueprint", summary)`',
-  "Do not implement code in this phase.",
-].join("\n"));
-
-const BLUEPRINT_GUIDANCE = Object.freeze([
-  "## Blueprint phase",
-  "Read the clarifications artifact (if present) and plan only within recorded Decisions;",
-  "Open Questions that would block the design must be re-asked via ask_user_question, not assumed.",
-  'Produce ONE plan document and save it with `save_artifact("plan", content)`.',
-  "This pipeline is read-only: it produces a plan a human or a native-mode agent executes;",
-  "do not write source files here (sandbox write modes are blocked).",
-  "Write changes as exact, copy-pasteable before/after code — never as prose instructions.",
-  "The ENGINE derive-checks the document — these are hard gates, not suggestions:",
-  "- frontmatter: `status: ready`, `phase_count: N`, `phases: [{n: 1, title: ...}, ...]`",
-  "- `phases:` / `phase_count` MUST match the `## Phase N:` body headings exactly (fenced examples ignored)",
-  "- every `file:line` citation MUST resolve against the working tree at this revision",
-  "Each `## Phase N: <title>` section contains:",
-  "- `### Changes Required` — per file: path + the exact intended change",
-  "- `### Success Criteria` — `#### Automated Verification:` (runnable commands) and",
-  "  `#### Manual Verification:` checklists",
-  "Phases must be independently implementable in order, each leaving the tree working.",
-  'When ready: `advance_phase("validate", summary)`.',
-].join("\n"));
-
-const VALIDATE_GUIDANCE = Object.freeze([
-  "## Validate phase (adversarial plan review)",
-  "Nothing has been implemented — you are reviewing the PLAN, not a diff.",
-  "Read the goal artifact (verbatim brief), the clarifications artifact (recorded Decisions),",
-  "and the plan. For each plan phase check against the working tree:",
-  "- every cited `file:line` still resolves and says what the plan claims",
-  "- every file the phase edits exists (or is created by an earlier phase)",
-  "- no phase contradicts a recorded Decision or silently resolves an Open Question",
-  "- the Success Criteria are actually runnable and actually prove the change",
-  "- phases are independently implementable in the stated order",
-  "Write ONE review via `save_artifact(\"validation\", content)` with frontmatter:",
-  "- `status: ready`",
-  "- `blockers_count: <int >= 0>`  # MEASURED — routing key; not prose",
-  "- `verdict: pass | fail`  # pass requires blockers_count === 0",
-  "Each blocker needs a resolvable `file:line` citation.",
-  "Then finalize: `answer[\"content\"] = <the reviewed plan + review summary>; answer[\"ready\"] = True`.",
-  "If `blockers_count > 0`, the engine re-enters blueprint (bounded by maxBackwardJumps).",
-].join("\n"));
-
-const GUIDANCE: Readonly<Record<Phase, string>> = Object.freeze({
-  clarify: CLARIFY_GUIDANCE,
-  research: RESEARCH_GUIDANCE,
-  blueprint: BLUEPRINT_GUIDANCE,
-  validate: VALIDATE_GUIDANCE,
-});
-
-export function phaseGuidance(phase: Phase): string {
-  return GUIDANCE[phase];
-}

package/src/state/index.ts

@@ -1,24 +0,0 @@
-/**
- * Barrel for the RLM run-state module.
- *
- * Re-exports every public symbol so `core/engine.ts` and `mode/rlm-mode.ts`
- * import from one door. Type-only re-exports use `export type`.
- */
-
-export { generateRunId, runsDir, runDir, trailPath, contextPath, snapshotPath } from "./paths.ts";
-export type {
-  UsageRow,
-  RunHeader,
-  TurnRow,
-  CompactionRow,
-  TerminalRow,
-  TodoRow,
-  PhaseRow,
-  Row,
-} from "./rows.ts";
-export { STATE_SCHEMA_VERSION, isHeader, isTurn, isCompaction, isPhase, isTodo, isTerminal, isRow } from "./rows.ts";
-export { appendRow, appendTodoRow, pruneRuns, writeContextSidecar } from "./writes.ts";
-export { readRows, readHeader, readContextSidecar, readLibrarySidecars, listRunIds, resolveRunId } from "./reads.ts";
-export type { LibrarySlot } from "./reads.ts";
-export { reconstructRlmState } from "./resume.ts";
-export type { PhaseRecon, ReconstructResult } from "./resume.ts";

package/src/state/internal.ts

@@ -1,46 +0,0 @@
-/** Internal helpers shared across the RLM run-state module. */
-
-import { access, readdir } from "node:fs/promises";
-import { errorMessage } from "../util/errors.ts";
-
-export { errorMessage } from "../util/errors.ts";
-
-export interface FailSoftOptions {
-  readonly label?: string;
-  readonly warn?: boolean;
-}
-
-const DEFAULT_FAIL_SOFT_OPTIONS = Object.freeze({});
-
-export const warn = (e: unknown): void => console.warn(`[rlm-state] ${errorMessage(e)}`);
-
-export async function failSoft<T>(
-  fn: () => Promise<T>,
-  fallback: T,
-  options: FailSoftOptions = DEFAULT_FAIL_SOFT_OPTIONS,
-): Promise<T> {
-  try {
-    return await fn();
-  } catch (e) {
-    if (options.warn !== false) warn(options.label ? `${options.label}: ${errorMessage(e)}` : e);
-    return fallback;
-  }
-}
-
-export async function listDirectoriesSorted(root: string): Promise<string[]> {
-  const entries = await readdir(root, { withFileTypes: true });
-  return entries
-    .filter((entry) => entry.isDirectory())
-    .map((entry) => entry.name)
-    .sort()
-    .reverse();
-}
-
-export async function pathExists(path: string): Promise<boolean> {
-  try {
-    await access(path);
-    return true;
-  } catch {
-    return false;
-  }
-}

package/src/state/paths.ts

@@ -1,44 +0,0 @@
-/**
- * Pure path/id helpers for the RLM run-state module.
- *
- * Run-IDs are filename-sortable ISO-like slugs with a random hex suffix
- * for sub-second collision safety. All helpers are pure — no I/O.
- */
-
-import { randomBytes } from "node:crypto";
-import { isAbsolute, join } from "node:path";
-
-const RUN_ID_SUFFIX_BYTES = 2;
-const ISO_DATETIME_LENGTH = 19;
-
-/** `YYYY-MM-DD_HH-MM-SS-<4hex>` — filename-sortable, sub-second collision-safe.
- *
- * Prune ordering in writes.ts:pruneRuns depends on the ISO-slug format producing
- * chronologically sortable strings. If the format changes, update pruning logic
- * to maintain oldest-first deletion. */
-export function generateRunId(
-  now: Date = new Date(),
-  suffix: string = randomBytes(RUN_ID_SUFFIX_BYTES).toString("hex"),
-): string {
-  const pad = (n: number): string => String(n).padStart(2, "0");
-  const iso = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}T${pad(now.getHours())}:${pad(now.getMinutes())}:${pad(now.getSeconds())}`;
-  return `${iso.slice(0, ISO_DATETIME_LENGTH).replaceAll(":", "-").replace("T", "_")}-${suffix}`;
-}
-
-export const runsDir = (cwd: string, dir: string): string =>
-  isAbsolute(dir) ? dir : join(cwd, dir);
-
-export const runDir = (cwd: string, dir: string, runId: string): string => join(runsDir(cwd, dir), runId);
-
-export const trailPath = (cwd: string, dir: string, runId: string): string => join(runDir(cwd, dir, runId), "trail.jsonl");
-
-export const contextPath = (cwd: string, dir: string, runId: string, json: boolean, index = 0): string =>
-  join(runDir(cwd, dir, runId), index === 0
-    ? (json ? "context.json" : "context.txt")
-    : `context.${index}.${json ? "json" : "txt"}`);
-
-/** R-C1: per-turn snapshot files — `sandbox-<turn>.pkl` so resume can fall back to a prior turn if the latest rename failed. */
-export function snapshotPath(cwd: string, dir: string, runId: string, turn?: number): string {
-  const name = turn !== undefined ? `sandbox-${turn}.pkl` : "sandbox.pkl";
-  return join(runDir(cwd, dir, runId), name);
-}

package/src/state/reads.ts

@@ -1,133 +0,0 @@
-/**
- * Fail-soft JSONL readers for the RLM run-state module.
- *
- * `readRows` parses each line in its own try/catch so a truncated trailing
- * line cannot erase prior rows. `listRunIds` sorts directories newest-first
- * by the slug (ISO-like timestamps are self-sorting).
- */
-
-import { open, readdir, readFile } from "node:fs/promises";
-import { join } from "node:path";
-import { runsDir, runDir, trailPath, contextPath } from "./paths.ts";
-import { isHeader, isRow, type RunHeader, type Row } from "./rows.ts";
-import { errorMessage, failSoft, listDirectoriesSorted, pathExists, warn } from "./internal.ts";
-
-/**
- * Raw JSONL lines of a run's trail, in order. Missing or unreadable file → [].
- * Shared by the fail-soft reader here and the hole-detecting reader in resume.ts, which
- * differ only in how they treat a bad line.
- */
-export async function readTrailLines(cwd: string, dir: string, runId: string): Promise<string[]> {
-  const path = trailPath(cwd, dir, runId);
-  if (!await pathExists(path)) return [];
-  const content = await failSoft(
-    () => readFile(path, "utf-8"),
-    undefined as string | undefined,
-  );
-  const trimmed = content?.trim();
-  return trimmed ? trimmed.split("\n") : [];
-}
-
-/** Every well-formed row, in trail order. Malformed line → one warn, skipped. */
-export async function readRows(cwd: string, dir: string, runId: string): Promise<Row[]> {
-  const lines = await readTrailLines(cwd, dir, runId);
-  const rows: Row[] = [];
-  for (const line of lines) {
-    try {
-      const row = JSON.parse(line) as unknown;
-      if (isRow(row)) rows.push(row);
-      else warn("skipping invalid JSONL row shape");
-    } catch (e) {
-      warn(`skipping malformed JSONL row — ${errorMessage(e)}`);
-    }
-  }
-  return rows;
-}
-
-/** Read the first line of a trail file without reading the entire file (P1). */
-async function readFirstLine(path: string): Promise<string | undefined> {
-  return await failSoft(async () => {
-    const file = await open(path, "r");
-    try {
-      const stats = await file.stat();
-      const size = Math.min(stats.size, 65536);
-      if (size <= 0) return undefined;
-      const buffer = Buffer.alloc(size);
-      const { bytesRead } = await file.read(buffer, 0, size, 0);
-      const content = buffer.toString("utf-8", 0, bytesRead);
-      const nl = content.indexOf("\n");
-      return nl >= 0 ? content.slice(0, nl) : content.trim() || undefined;
-    } finally {
-      await file.close();
-    }
-  }, undefined as string | undefined, { warn: false });
-}
-
-/** First well-formed header row, or undefined. Bounded read — never reads the full trail (P1). */
-export async function readHeader(cwd: string, dir: string, runId: string): Promise<RunHeader | undefined> {
-  const line = await readFirstLine(trailPath(cwd, dir, runId));
-  if (!line) return undefined;
-  try {
-    const row = JSON.parse(line) as unknown;
-    return isHeader(row) ? row : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-/** Reload context from a persistent sidecar file. */
-export async function readContextSidecar(cwd: string, dir: string, runId: string, json: boolean): Promise<unknown> {
-  const path = contextPath(cwd, dir, runId, json);
-  if (!await pathExists(path)) return undefined;
-  const content = await failSoft(
-    () => readFile(path, "utf-8"),
-    undefined as string | undefined,
-  );
-  if (content === undefined) return undefined;
-  try {
-    return json ? JSON.parse(content) as unknown : content;
-  } catch (e) {
-    warn(e);
-    return undefined;
-  }
-}
-
-const LIBRARY_SIDECAR = /^context\.(\d+)\.(json|txt)$/;
-
-export interface LibrarySlot {
-  readonly index: number;
-  readonly payload: unknown;
-}
-
-/** Fail-soft lister for load_library resume sidecars (`context.<index>.json|txt`). */
-export async function readLibrarySidecars(cwd: string, dir: string, runId: string): Promise<LibrarySlot[]> {
-  const entries = await failSoft(() => readdir(runDir(cwd, dir, runId)), [] as string[]);
-  const slots: LibrarySlot[] = [];
-  for (const name of entries) {
-    const m = LIBRARY_SIDECAR.exec(name);
-    if (!m) continue;
-    const index = Number(m[1]);
-    const json = m[2] === "json";
-    const content = await failSoft(
-      () => readFile(join(runDir(cwd, dir, runId), name), "utf-8"),
-      undefined as string | undefined,
-    );
-    if (content === undefined) continue;
-    try {
-      slots.push({ index, payload: json ? JSON.parse(content) as unknown : content });
-    } catch (e) { warn(e); }
-  }
-  return slots.sort((a, b) => a.index - b.index);
-}
-
-/** Enumerate run-ids by directory listing; newest first (slug sorts chronologically). */
-export async function listRunIds(cwd: string, dir: string): Promise<string[]> {
-  return await failSoft(() => listDirectoriesSorted(runsDir(cwd, dir)), [], { warn: false });
-}
-
-/** `@latest` / explicit id resolution. */
-export async function resolveRunId(cwd: string, dir: string, ref: string): Promise<string | undefined> {
-  const ids = await listRunIds(cwd, dir);
-  if (ref === "@latest") return ids[0];
-  return ids.includes(ref) ? ref : undefined;
-}