@hicaru/pi-rlm 0.2.0 → 0.2.2

package/src/bridge/fallback-todo.ts

@@ -1,137 +0,0 @@
-import { formatError } from "../util/errors.ts";
-
-type TaskStatus = "pending" | "in_progress" | "completed" | "deleted";
-
-interface Task {
-  readonly id: number;
-  readonly subject: string;
-  readonly description?: string;
-  readonly status: TaskStatus;
-  readonly activeForm?: string;
-  readonly blockedBy?: readonly number[];
-  readonly owner?: string;
-}
-
-interface TodoParams {
-  readonly id?: number;
-  readonly subject?: string;
-  readonly description?: string;
-  readonly status?: TaskStatus;
-  readonly activeForm?: string;
-  readonly blockedBy?: readonly number[];
-  readonly addBlockedBy?: readonly number[];
-  readonly removeBlockedBy?: readonly number[];
-  readonly owner?: string;
-  readonly filterStatus?: string;
-  readonly includeDeleted?: boolean;
-}
-
-const TODO_STATUSES = Object.freeze(new Set<unknown>(["pending", "in_progress", "completed", "deleted"]));
-
-function isTaskStatus(value: unknown): value is TaskStatus {
-  return TODO_STATUSES.has(value);
-}
-
-function numericArray(value: unknown): readonly number[] | undefined {
-  return Array.isArray(value) ? Object.freeze(value.filter((n): n is number => typeof n === "number")) : undefined;
-}
-
-function toTodoParams(raw: Record<string, unknown>): TodoParams {
-  const blockedBy = numericArray(raw.blockedBy);
-  const addBlockedBy = numericArray(raw.addBlockedBy);
-  const removeBlockedBy = numericArray(raw.removeBlockedBy);
-  return Object.freeze({
-    ...(typeof raw.id === "number" ? { id: raw.id } : {}),
-    ...(typeof raw.subject === "string" ? { subject: raw.subject } : {}),
-    ...(typeof raw.description === "string" ? { description: raw.description } : {}),
-    ...(isTaskStatus(raw.status) ? { status: raw.status } : {}),
-    ...(typeof raw.activeForm === "string" ? { activeForm: raw.activeForm } : {}),
-    ...(blockedBy ? { blockedBy } : {}),
-    ...(addBlockedBy ? { addBlockedBy } : {}),
-    ...(removeBlockedBy ? { removeBlockedBy } : {}),
-    ...(typeof raw.owner === "string" ? { owner: raw.owner } : {}),
-    ...(typeof raw.filterStatus === "string" ? { filterStatus: raw.filterStatus } : {}),
-    ...(raw.includeDeleted === true ? { includeDeleted: true } : {}),
-  });
-}
-
-function patchedBlockedBy(task: Task, params: TodoParams): readonly number[] | undefined {
-  if (params.blockedBy) return params.blockedBy;
-
-  let next = task.blockedBy ?? Object.freeze([] as readonly number[]);
-  if (params.addBlockedBy) next = Object.freeze([...next, ...params.addBlockedBy]);
-
-  if (params.removeBlockedBy) {
-    const removeSet = new Set(params.removeBlockedBy);
-    next = Object.freeze(next.filter((n) => !removeSet.has(n)));
-  }
-  return next.length ? next : undefined;
-}
-
-function taskLines(task: Task): readonly string[] {
-  const lines: string[] = [`#${task.id} [${task.status}] ${task.subject}`];
-  if (task.description) lines.push(`  description: ${task.description}`);
-  if (task.activeForm) lines.push(`  activeForm: ${task.activeForm}`);
-  if (task.blockedBy?.length) lines.push(`  blockedBy: ${task.blockedBy.map((n) => `#${n}`).join(", ")}`);
-  if (task.owner) lines.push(`  owner: ${task.owner}`);
-  return lines;
-}
-
-function withPatch(task: Task, params: TodoParams): Task {
-  const blockedBy = patchedBlockedBy(task, params);
-  return Object.freeze({
-    ...task,
-    ...(params.subject !== undefined ? { subject: params.subject } : {}),
-    ...(params.description !== undefined ? { description: params.description } : {}),
-    ...(params.status !== undefined ? { status: params.status } : {}),
-    ...(params.activeForm !== undefined ? { activeForm: params.activeForm } : {}),
-    ...(blockedBy ? { blockedBy } : {}),
-    ...(params.owner !== undefined ? { owner: params.owner } : {}),
-  });
-}
-
-export function createTodoFallback(): (action: string, params: Record<string, unknown>) => Promise<string> {
-  let nextId = 1;
-  let tasks: readonly Task[] = Object.freeze([]);
-  const fmt = (task: Task): string => taskLines(task)[0] ?? `#${task.id}`;
-
-  const apply = (action: string, rawParams: Record<string, unknown>): string => {
-    const params = toTodoParams(rawParams);
-    if (action === "clear") {
-      const count = tasks.length;
-      tasks = Object.freeze([]);
-      nextId = 1;
-      return `Cleared ${count} task(s).`;
-    }
-    if (action === "create") {
-      const subject = typeof params.subject === "string" && params.subject.trim() ? params.subject.trim() : undefined;
-      if (!subject) return formatError("create requires subject");
-      const task = withPatch(Object.freeze({ id: nextId, subject, status: "pending" }), params);
-      nextId += 1;
-      tasks = Object.freeze([...tasks, task]);
-      return `Created ${fmt(task)}`;
-    }
-    if (action === "list") {
-      const filter = params.filterStatus ?? params.status;
-      const includeDeleted = params.includeDeleted === true;
-      const rows = tasks.filter((task) => (includeDeleted || task.status !== "deleted") && (!filter || task.status === filter)).map(fmt);
-      return rows.length ? rows.join("\n") : "No tasks.";
-    }
-    const id = params.id;
-    const task = id !== undefined ? tasks.find((item) => item.id === id) : undefined;
-    if (!task) return formatError(`task #${id ?? "?"} not found`);
-    if (action === "get") return taskLines(task).join("\n");
-    if (action === "delete") {
-      const deleted = Object.freeze({ ...task, status: "deleted" as const });
-      tasks = Object.freeze(tasks.map((item) => item.id === task.id ? deleted : item));
-      return `Deleted ${fmt(deleted)}`;
-    }
-    if (action === "update") {
-      const updated = withPatch(task, params);
-      tasks = Object.freeze(tasks.map((item) => item.id === task.id ? updated : item));
-      return `Updated ${fmt(updated)}`;
-    }
-    return formatError(`unknown todo action '${action}'`);
-  };
-  return async (action, params) => apply(action, params);
-}

package/src/bridge/interactive.ts

@@ -1,65 +0,0 @@
-import type { AskAnswer, AskQuestion } from "../sandbox/protocol.ts";
-import type { SubLlmHandlers } from "../sandbox/sandbox.ts";
-import type { RlmEmitter } from "../tool/rlm-events.ts";
-import { formatError } from "../util/errors.ts";
-
-export interface InteractiveBridgeOpts {
-  readonly onAskUserQuestion?: (questions: readonly AskQuestion[]) => Promise<AskAnswer[]>;
-  readonly onTodo?: (action: string, params: Record<string, unknown>) => Promise<string>;
-  readonly onTodoRow?: (action: string, params: Record<string, unknown>, result: string) => void | Promise<void>;
-  readonly emitter?: RlmEmitter;
-  readonly depth: number;
-  readonly parentId?: string;
-}
-
-export function buildInteractiveHandlers(opts: InteractiveBridgeOpts): {
-  askUserQuestion: SubLlmHandlers["askUserQuestion"];
-  todo: SubLlmHandlers["todo"];
-} {
-  return {
-    async askUserQuestion(questions, depth) {
-      if (depth > 0) return questions.map((q) => ({
-        question: q.question,
-        selected: [],
-        custom: formatError("ask_user_question not available inside rlm_query sub-calls"),
-      }));
-
-      const id = opts.emitter?.emitSubcallCreated({
-        kind: "tool", parentId: opts.parentId,
-        label: "ask_user_question",
-        args: `${questions.length} question(s)`,
-        depth,
-      });
-      try {
-        const cb = opts.onAskUserQuestion;
-        if (!cb) throw new Error("ask_user_question not configured (no onAskUserQuestion callback)");
-        const answers = await cb(questions);
-        if (id) opts.emitter?.emitSubcallUpdated({ id, status: "done" });
-        return answers;
-      } catch (err) {
-        if (id) opts.emitter?.emitSubcallUpdated({ id, status: "error", detail: String(err) });
-        throw err;
-      }
-    },
-
-    async todo(action, params, depth) {
-      const id = opts.emitter?.emitSubcallCreated({
-        kind: "tool", parentId: opts.parentId,
-        label: `todo:${action}`,
-        args: params.subject ? String(params.subject) : String(params.id ?? ""),
-        depth,
-      });
-      try {
-        const cb = opts.onTodo;
-        if (!cb) throw new Error("todo not configured (no onTodo callback)");
-        const result = await cb(action, params);
-        await opts.onTodoRow?.(action, params, result);
-        if (id) opts.emitter?.emitSubcallUpdated({ id, status: "done", resultPreview: result.slice(0, 80) });
-        return result;
-      } catch (err) {
-        if (id) opts.emitter?.emitSubcallUpdated({ id, status: "error", detail: String(err) });
-        throw err;
-      }
-    },
-  };
-}

package/src/bridge/llm-query.ts

@@ -1,156 +0,0 @@
-/**
- * The `llm_query` / `llm_query_batched` bridge: turns sandbox sub-LLM interrupts into
- * real (serverless) completions on the configured *worker* model, reporting each call to the
- * RlmEmitter for progressive TUI re-rendering.
- *
- * Caps enforce the divide-and-conquer budget from the RLM method: per-prompt size and batch
- * fan-out are bounded, and batches run through a fixed-size concurrency pool.
- *
- * Every input that can change between calls (worker model, emitter, parent node, depth,
- * remaining budget) is an accessor, so a single bridge instance serves both the headless
- * engine — which binds them once per run — and the native `repl` tool, which swaps them per
- * invocation without recreating the sandbox.
- */
-
-import type { Api, Model, Usage } from "@earendil-works/pi-ai";
-import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
-import type { RlmEmitter } from "../tool/rlm-events.ts";
-import { displayModelRef, resolveModelId } from "../config/settings.ts";
-import { checkResourceLimits, type RemainingResources } from "../core/resource-limits.ts";
-import type { Sampling } from "../core/types.ts";
-import { type ChatMsg, modelComplete } from "./model.ts";
-import { previewText } from "../text/preview.ts";
-import { errorMessage, formatError, isErrorText } from "../util/errors.ts";
-import { mapPool } from "../util/concurrency.ts";
-
-/**
- * The config slice this bridge reads. Structurally satisfied by `RlmConfig`, and re-read on
- * every call so `/rlm-config` changes take effect without rebuilding the sandbox.
- */
-export interface LlmBridgeConfig {
-  readonly maxPromptChars: number;
-  readonly maxConcurrentSubcalls: number;
-  readonly subSystemPrompt?: string;
-  readonly subSampling?: Sampling;
-}
-
-export interface LlmBridgeOptions {
-  /** Resolved per call so provider/config changes between calls are picked up. */
-  readonly workerModel: () => Model<Api>;
-  readonly registry: ModelRegistry;
-  readonly config: () => LlmBridgeConfig;
-  readonly signal?: AbortSignal;
-  readonly onUsage?: (usage: Usage, model: Model<Api>) => void;
-  /** Parent run's remaining budget/timeout; checked before every sub-call. */
-  readonly remainingBudget?: () => RemainingResources | undefined;
-  /** Live RlmDetails reporting target, resolved per call. */
-  readonly emitter?: () => RlmEmitter | undefined;
-  readonly parentId?: () => string | undefined;
-  readonly depth?: () => number;
-}
-
-/** Provider failures that a smaller batch or a cheaper model might get past. */
-const RETRYABLE_HINT = /credit|402|payment|quota|rate.limit/i;
-
-export interface LlmBridge {
-  llmQuery(prompt: string, model: string | null, depth: number): Promise<string>;
-  llmQueryBatched(prompts: readonly string[], model: string | null, depth: number): Promise<string[]>;
-}
-
-/** Batch outcome summary, or undefined when every prompt succeeded. */
-function batchError(failed: number, total: number): string | undefined {
-  if (failed === 0) return undefined;
-  return failed === total
-    ? `all ${total} sub-calls failed — reduce batch size or try llm_query individually`
-    : `${failed}/${total} sub-calls failed`;
-}
-
-export function createLlmBridge(opts: LlmBridgeOptions): LlmBridge {
-  const displayModel = (model: string | null): string =>
-    displayModelRef(opts.registry, model, opts.workerModel());
-
-  // Run one completion; report cost/tokens via `track` (a per-call or per-batch accumulator).
-  async function complete1(prompt: string, model: string | null, track: (u: Usage) => void): Promise<string> {
-    const config = opts.config();
-    const rem = opts.remainingBudget?.();
-    if (rem !== undefined) {
-      const limitError = checkResourceLimits(rem);
-      if (limitError !== undefined) return limitError;
-    }
-    if (prompt.length > config.maxPromptChars) {
-      return formatError(`sub-LLM prompt exceeded the size limit (${prompt.length.toLocaleString()} chars > ${config.maxPromptChars.toLocaleString()}). Shorten or chunk the prompt before calling llm_query.`);
-    }
-    const resolved = model ? resolveModelId(opts.registry, model) : undefined;
-    if (model && !resolved) return formatError(`unknown model override '${model}'`);
-    const target = resolved ?? opts.workerModel();
-    try {
-      const messages: ChatMsg[] = [{ role: "user", content: prompt }];
-      const res = await modelComplete(messages, {
-        model: target,
-        registry: opts.registry,
-        system: config.subSystemPrompt,
-        maxTokens: config.subSampling?.maxTokens,
-        temperature: config.subSampling?.temperature,
-        reasoning: config.subSampling?.reasoning,
-        signal: opts.signal,
-      });
-      opts.onUsage?.(res.usage, target);
-      track(res.usage);
-      return res.text;
-    } catch (err) {
-      const msg = errorMessage(err);
-      const hint = RETRYABLE_HINT.test(msg) ? " — try smaller batches or individual llm_query calls" : "";
-      return formatError(`${msg}${hint}`);
-    }
-  }
-
-  return {
-    async llmQuery(prompt, model) {
-      const emitter = opts.emitter?.();
-      const id = emitter?.emitSubcallCreated({
-        kind: "llm", parentId: opts.parentId?.(), label: "llm_query",
-        model: displayModel(model), args: `prompt: ${previewText(prompt)}`,
-        depth: opts.depth?.() ?? 0,
-      });
-      let cost = 0;
-      let tokens = 0;
-      const out = await complete1(prompt, model, (u) => {
-        cost += u.cost.total;
-        tokens += u.totalTokens;
-      });
-      if (emitter && id !== undefined) emitter.emitSubcallUpdated({ id,
-        status: isErrorText(out) ? "error" : "done",
-        costUsd: cost, tokens, resultPreview: previewText(out),
-        detail: isErrorText(out) ? out : undefined,
-      });
-      return out;
-    },
-
-    async llmQueryBatched(prompts, model) {
-      const emitter = opts.emitter?.();
-      const id = emitter?.emitSubcallCreated({
-        kind: "batch", parentId: opts.parentId?.(), label: `llm_query ×${prompts.length}`,
-        model: displayModel(model), args: `prompt: ${previewText(prompts[0] ?? "")}`,
-        depth: opts.depth?.() ?? 0,
-      });
-      let cost = 0;
-      let tokens = 0;
-      const out = await mapPool(prompts, opts.config().maxConcurrentSubcalls, (p) =>
-        complete1(p, model, (u) => {
-          cost += u.cost.total;
-          tokens += u.totalTokens;
-        }),
-      );
-      const failed = out.filter(isErrorText).length;
-      const error = batchError(failed, out.length);
-      const firstPreview = previewText(out[0] ?? "");
-      const resultPreview = out.length > 1 ? `${firstPreview}  (+${out.length - 1} more)` : firstPreview;
-      if (emitter && id !== undefined) emitter.emitSubcallUpdated({ id,
-        status: error ? "error" : "done", costUsd: cost, tokens,
-        resultPreview, detail: error,
-        failedCount: failed, totalCount: out.length,
-      });
-      return out;
-    },
-  };
-}

package/src/bridge/pi-interactive.ts

@@ -1,41 +0,0 @@
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { InteractiveDeps } from "../core/types.ts";
-import type { AskAnswer, AskQuestion } from "../sandbox/protocol.ts";
-import { formatError } from "../util/errors.ts";
-import { createTodoFallback } from "./fallback-todo.ts";
-
-async function askViaUi(ctx: ExtensionContext, questions: readonly AskQuestion[]): Promise<AskAnswer[]> {
-  if (!ctx.hasUI) throw new Error("ask_user_question requires UI");
-  const answers = new Array<AskAnswer>(questions.length);
-  for (let i = 0; i < questions.length; i++) {
-    const q = questions[i];
-    if (!q) {
-      answers[i] = { question: "", selected: [], custom: formatError("malformed question") };
-      continue;
-    }
-    if (q.multiSelect) {
-      const selected: string[] = [];
-      while (true) {
-        const pick = await ctx.ui.select(`${q.header}: ${q.question}`, [...q.options.map((o) => o.label), "Done"]);
-        if (!pick || pick === "Done") break;
-        if (!selected.includes(pick)) selected.push(pick);
-      }
-      answers[i] = { question: q.question, selected };
-      continue;
-    }
-    const pick = await ctx.ui.select(`${q.header}: ${q.question}`, [...q.options.map((o) => o.label), "Type something."]);
-    if (!pick) answers[i] = { question: q.question, selected: [], custom: formatError("user cancelled") };
-    else if (pick === "Type something.") answers[i] = { question: q.question, selected: [], custom: await ctx.ui.input(q.question) ?? "" };
-    else answers[i] = { question: q.question, selected: [pick] };
-  }
-  return answers;
-}
-
-export function createPiInteractiveDeps(ctx: ExtensionContext): InteractiveDeps {
-  const fallbackTodo = createTodoFallback();
-  return Object.freeze({
-    onAskUserQuestion: (questions: readonly AskQuestion[]): Promise<AskAnswer[]> => askViaUi(ctx, questions),
-    onTodo: (action: string, params: Record<string, unknown>): Promise<string> =>
-      Promise.resolve(fallbackTodo(action, params)),
-  });
-}

package/src/bridge/rlm-query.ts

@@ -1,108 +0,0 @@
-/**
- * The `rlm_query` recursion bridge.
- *
- * A child RLM gets its own sandbox and iterates over the prompt as its context. At/over the
- * depth cap it degrades to a plain `llm_query` (ported from rlm/core/rlm.py `_subcall`). The
- * concurrency pool bounds parallel children for `rlm_query_batched`.
- *
- * As with the llm bridge, everything that can change between calls is an accessor, so the
- * headless engine (which binds them once per run) and the native `repl` tool (which swaps them
- * per invocation) share one implementation.
- */
-
-import type { RlmResult, RunRlm } from "../core/types.ts";
-import type { LlmBridge } from "./llm-query.ts";
-import type { RlmEmitter } from "../tool/rlm-events.ts";
-import { checkResourceLimits, type RemainingResources } from "../core/resource-limits.ts";
-import { errorMessage, formatError } from "../util/errors.ts";
-import { mapPool } from "../util/concurrency.ts";
-import { previewText } from "../text/preview.ts";
-
-/** The config slice this bridge reads; structurally satisfied by `RlmConfig`. */
-export interface RlmBridgeConfig {
-  readonly maxDepth: number;
-  readonly maxConcurrentSubcalls: number;
-}
-
-export interface RlmHandlers {
-  rlmQuery(prompt: string, model: string | null, depth: number): Promise<string>;
-  rlmQueryBatched(prompts: readonly string[], model: string | null, depth: number): Promise<string[]>;
-}
-
-export interface RlmBridgeOptions {
-  /**
-   * Spawns one child run. The engine passes its own `run` (self-recursion); the native tool
-   * passes a closure that builds a child engine bound to the current invocation's emitter.
-   */
-  readonly run: RunRlm;
-  readonly llm: LlmBridge;
-  readonly config: () => RlmBridgeConfig;
-  /** "provider/id" shown on the sub-call node; see `displayModelRef` in config/settings.ts. */
-  readonly modelLabel?: (override: string | null) => string;
-  /** Live RlmDetails reporting target, resolved per call. */
-  readonly emitter: () => RlmEmitter | undefined;
-  /** Parent subcall ID that this run is attached under, resolved per call. */
-  readonly parentNodeId?: () => string | undefined;
-  /** Returns the parent's remaining budget/timeout for seeding child runs. */
-  readonly remainingBudget?: () => RemainingResources | undefined;
-  /** Called with a child run's total cost/tokens so the parent LimitGuard debits it. */
-  readonly onChildUsage?: (costUsd: number, inputTokens: number, outputTokens: number) => void;
-}
-
-export function createRlmHandlers(opts: RlmBridgeOptions): RlmHandlers {
-  /**
-   * One child spawn. `childDepth` is the absolute depth the child will run at.
-   * Never throws: failures come back as "Error: ..." strings, matching the sandbox contract.
-   */
-  async function child(prompt: string, model: string | null, childDepth: number): Promise<string> {
-    // At the cap, a child RLM would just be an LM — short-circuit to a one-shot llm_query.
-    if (childDepth >= opts.config().maxDepth) {
-      return opts.llm.llmQuery(prompt, model, childDepth - 1);
-    }
-
-    const rem = opts.remainingBudget?.();
-    if (rem !== undefined) {
-      // Pre-spawn guard: refuse if the parent's budget or timeout is already exhausted
-      // (reference: _subcall checks remaining_budget/timeout before spawning).
-      const limitError = checkResourceLimits(rem);
-      if (limitError !== undefined) return limitError;
-    }
-
-    const emitter = opts.emitter();
-    const subId = emitter?.emitSubcallCreated({
-      kind: "rlm", parentId: opts.parentNodeId?.(), label: "rlm_query",
-      model: opts.modelLabel?.(model) ?? model ?? undefined,
-      detail: prompt.slice(0, 60),
-      depth: childDepth,
-    });
-
-    try {
-      const res: RlmResult = await opts.run({
-        rootPrompt: "",
-        context: prompt,
-        depth: childDepth,
-        parentNodeId: subId,
-        modelOverride: model ?? undefined,
-        remainingBudgetUsd: rem?.budgetUsd,
-        remainingTimeoutMs: rem?.timeoutMs,
-      });
-      opts.onChildUsage?.(res.costUsd, res.inputTokens, res.outputTokens);
-      // The child emits live cost/token deltas on the shared emitter as it runs, so the node
-      // must NOT also receive a final aggregate — that would double-count.
-      if (emitter && subId !== undefined) {
-        emitter.emitSubcallUpdated({ id: subId, status: "done", resultPreview: previewText(res.answer) });
-      }
-      return res.answer;
-    } catch (err) {
-      const msg = errorMessage(err);
-      if (emitter && subId !== undefined) emitter.emitSubcallUpdated({ id: subId, status: "error", detail: msg });
-      return formatError(`child RLM failed - ${msg}`);
-    }
-  }
-
-  return {
-    rlmQuery: (prompt, model, depth) => child(prompt, model, depth + 1),
-    rlmQueryBatched: (prompts, model, depth) =>
-      mapPool(prompts, opts.config().maxConcurrentSubcalls, (p) => child(p, model, depth + 1)),
-  };
-}

package/src/core/artifacts.ts

@@ -1,89 +0,0 @@
-/**
- * Artifact plumbing for the gated RLM pipeline: goal capture, baseline dirty-tree
- * snapshot, and timestamped stage artifact writes under `.rlm/artifacts/`.
- */
-import { execFileSync } from "node:child_process";
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import type { Result } from "../util/errors.ts";
-import { errorMessage } from "../util/errors.ts";
-
-export const ARTIFACTS_DIR = ".rlm/artifacts";
-
-const stamp = (): string => new Date().toISOString().replace(/[:.]/g, "-");
-
-export interface GoalCapture {
-  readonly goalPath: string;      // repo-relative
-  readonly baselinePath: string;  // repo-relative
-}
-
-export type SaveOutcome =
-  | { readonly ok: true; readonly path: string }
-  | { readonly ok: false; readonly error: string };
-
-export type GoalCaptureResult =
-  | { readonly ok: true; readonly value: GoalCapture }
-  | { readonly ok: false; readonly error: string };
-
-/**
- * Capture the user's brief VERBATIM: no frontmatter, no headers — the raw file
- * is the only artifact that preserves explicit user constraints unrefracted. The
- * baseline snapshot records paths ALREADY dirty before the run, so validate
- * judges only the run's own delta. Best-effort: git failure ⇒ empty baseline.
- * Failures never throw (unwritable cwd etc.) — returns error for the engine to surface.
- */
-export function captureGoal(cwd: string, brief: string): GoalCaptureResult {
-  try {
-    const ts = stamp();
-    const dir = join(ARTIFACTS_DIR, "goal");
-    mkdirSync(join(cwd, dir), { recursive: true });
-    const goalPath = join(dir, `goal-${ts}.md`);
-    writeFileSync(join(cwd, goalPath), brief, "utf-8");
-    let paths: readonly string[] = [];
-    try {
-      paths = execFileSync("git", ["status", "--short"], {
-        cwd,
-        encoding: "utf-8",
-        stdio: ["ignore", "pipe", "ignore"],
-      })
-        .split("\n")
-        .filter((l) => l.trim() !== "")
-        .map((l) => {
-          const rest = l.slice(3).trim();
-          const arrow = rest.indexOf(" -> ");
-          return arrow >= 0 ? rest.slice(arrow + 4).trim() : rest;
-        });
-    } catch {
-      paths = [];
-    }
-    const baselinePath = join(dir, `baseline-${ts}.json`);
-    writeFileSync(join(cwd, baselinePath), JSON.stringify({ paths }, null, 2), "utf-8");
-    return { ok: true, value: { goalPath, baselinePath } };
-  } catch (err) {
-    const message = errorMessage(err);
-    return { ok: false, error: message };
-  }
-}
-
-/** Write a stage artifact under its dir; timestamped so runs never collide. */
-export function saveArtifact(cwd: string, dir: string, slug: string, content: string): SaveOutcome {
-  try {
-    const rel = join(ARTIFACTS_DIR, dir, `${stamp()}_${slug}.md`);
-    mkdirSync(join(cwd, ARTIFACTS_DIR, dir), { recursive: true });
-    writeFileSync(join(cwd, rel), content, "utf-8");
-    return { ok: true, path: rel };
-  } catch (err) {
-    const message = errorMessage(err);
-    return { ok: false, error: message };
-  }
-}
-
-/** Read a previously saved artifact (repo-relative path). Failures never throw. */
-export function readArtifact(cwd: string, relPath: string): Result<string, string> {
-  try {
-    return { ok: true, value: readFileSync(join(cwd, relPath), "utf-8") };
-  } catch (err) {
-    const message = errorMessage(err);
-    return { ok: false, error: `could not read artifact ${relPath}: ${message}` };
-  }
-}