forgedock 1.0.22 → 1.1.2

package/bin/batch-runner.mjs

@@ -0,0 +1,339 @@
+#!/usr/bin/env node
+/**
+ * bin/batch-runner.mjs — Batch driver for the ForgeDock pipeline eval harness (#1285)
+ *
+ * Iterates a corpus of GitHub issue numbers, invokes runCommand() (from
+ * bin/runner.mjs) for each issue against the /work-on spec, and writes a
+ * structured per-run results file consumable by scripts/eval-gate-scorecard.mjs.
+ *
+ * This is the batch/corpus increment of the standalone runtime — the natural
+ * next step after bin/runner.mjs's single-command foundational increment (#1151).
+ *
+ * Exports (all pure, no SDK, no network):
+ *   loadCorpus(path)                           → {corpus_version, issues}
+ *   makeRunResult(issue, status, opts)         → RunResult object
+ *   classifyRunnerResult(result)               → "success" | "failure" | "incomplete"
+ *   writeResults(outputPath, results, meta)    → void
+ *   runCorpus(opts)                            → Promise<RunResult[]>
+ *
+ * CLI usage:
+ *   node bin/batch-runner.mjs <corpus.json> [output.json]
+ *   node bin/batch-runner.mjs <corpus.json> [output.json] --dry-run
+ *
+ *   ANTHROPIC_API_KEY must be set for live runs.
+ *   FORGEDOCK_MODEL overrides the model (default: runner.mjs default).
+ *
+ * Corpus file format (docs/spec/eval-run-result.md):
+ *   { "corpus_version": "v1", "issues": [1001, 1002, 1003] }
+ *
+ * Output file format:
+ *   { "corpus_version": "v1", "runs": [ ...RunResult ] }
+ *
+ * See docs/spec/eval-run-result.md for the full JSON schema.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+// ---------------------------------------------------------------------------
+// Corpus loading
+// ---------------------------------------------------------------------------
+
+/**
+ * Load and validate a corpus JSON file.
+ *
+ * Throws a descriptive Error if the file is missing, invalid JSON, or does not
+ * contain a non-empty integer array at the "issues" key.
+ *
+ * @param {string} corpusPath - Absolute or relative path to the corpus JSON.
+ * @returns {{ corpus_version: string|null, issues: number[] }}
+ */
+export function loadCorpus(corpusPath) {
+  let raw;
+  try {
+    raw = readFileSync(corpusPath, "utf-8");
+  } catch (e) {
+    throw new Error(`Cannot read corpus file "${corpusPath}": ${e.message}`);
+  }
+
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch (e) {
+    throw new Error(`Corpus file "${corpusPath}" contains invalid JSON: ${e.message}`);
+  }
+
+  if (!data || typeof data !== "object") {
+    throw new Error(`Corpus file must be a JSON object; got ${typeof data}`);
+  }
+  if (!Array.isArray(data.issues) || data.issues.length === 0) {
+    throw new Error(`Corpus file must contain a non-empty "issues" array`);
+  }
+  for (let i = 0; i < data.issues.length; i++) {
+    const n = data.issues[i];
+    if (typeof n !== "number" || !Number.isInteger(n) || n <= 0) {
+      throw new Error(
+        `issues[${i}]: must be a positive integer (got ${JSON.stringify(n)})`,
+      );
+    }
+  }
+
+  return {
+    corpus_version: data.corpus_version ?? null,
+    issues: data.issues,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Run-result construction helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Map a runCommand() result status + stop reason to a scorecard status.
+ *
+ * runCommand() returns:
+ *   status: "complete" | "incomplete" | "dry-run" | "max-iterations"
+ *
+ * We map these to the eval-result schema's status:
+ *   "success"    — run completed cleanly (status "complete")
+ *   "incomplete" — run was cut short (status "incomplete" or "max-iterations" or "dry-run")
+ *
+ * The caller is responsible for "failure" — that requires inspecting GitHub
+ * state (whether the issue reached workflow:merged). For the purposes of the
+ * batch driver, a clean runner completion is classified as "success"; the
+ * scorecard consumer or a post-run hook can downgrade to "failure" by
+ * inspecting the issue label state.
+ *
+ * @param {{ status: string, stopReason?: string }} result
+ * @returns {"success" | "incomplete"}
+ */
+export function classifyRunnerResult(result) {
+  if (result.status === "complete") return "success";
+  return "incomplete";
+}
+
+/**
+ * Construct a per-run result object conforming to docs/spec/eval-run-result.md.
+ *
+ * @param {number} issue - GitHub issue number.
+ * @param {"success"|"failure"|"incomplete"|"error"} status
+ * @param {object} [opts]
+ * @param {number} [opts.wallClockMs]        - Wall-clock duration (ms).
+ * @param {number} [opts.interventionCount]  - Human intervention count.
+ * @param {number|null} [opts.cost]          - Token cost (null until #1255).
+ * @param {number} [opts.iterations]         - Tool-loop iteration count.
+ * @param {string} [opts.stopReason]         - Anthropic stop_reason or "max_iterations".
+ * @param {string|null} [opts.error]         - Error message when status === "error".
+ * @param {string} [opts.specVersion]        - Package version at run time.
+ * @param {string} [opts.model]              - Model used.
+ * @param {string} [opts.runAt]              - ISO-8601 timestamp.
+ * @returns {object}
+ */
+export function makeRunResult(issue, status, opts = {}) {
+  return {
+    issue,
+    status,
+    wallClockMs: opts.wallClockMs ?? 0,
+    interventionCount: opts.interventionCount ?? 0,
+    cost: opts.cost !== undefined ? opts.cost : null,
+    iterations: opts.iterations ?? null,
+    stopReason: opts.stopReason ?? null,
+    error: opts.error ?? null,
+    specVersion: opts.specVersion ?? null,
+    model: opts.model ?? null,
+    runAt: opts.runAt ?? new Date().toISOString(),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Output writing
+// ---------------------------------------------------------------------------
+
+/**
+ * Serialize run results to a JSON file.
+ * Creates parent directories as needed.
+ *
+ * @param {string} outputPath   - Absolute or relative path to write.
+ * @param {object[]} results    - Array of per-run result objects.
+ * @param {object} [meta]       - Top-level metadata (corpus_version, spec_version, model, corpus_size).
+ * @returns {void}
+ */
+export function writeResults(outputPath, results, meta = {}) {
+  const resolved = resolve(outputPath);
+  mkdirSync(dirname(resolved), { recursive: true });
+  const payload = {
+    corpus_version: meta.corpus_version ?? null,
+    corpus_size: meta.corpus_size ?? null,
+    spec_version: meta.spec_version ?? null,
+    model: meta.model ?? null,
+    generated_at: new Date().toISOString(),
+    runs: results,
+  };
+  writeFileSync(resolved, JSON.stringify(payload, null, 2) + "\n", "utf-8");
+}
+
+// ---------------------------------------------------------------------------
+// Batch orchestrator
+// ---------------------------------------------------------------------------
+
+/**
+ * Run the full corpus headlessly.
+ *
+ * For each issue number in `corpus.issues`, invokes runCommand() against the
+ * /work-on spec in a shared working directory, records a per-run result, and
+ * returns the full array of results.
+ *
+ * Does NOT write output itself — callers should call writeResults() on the
+ * returned array. The CLI entry point below does this automatically.
+ *
+ * @param {object} opts
+ * @param {string} opts.commandsDir           - Absolute path to commands/.
+ * @param {{ corpus_version: string|null, issues: number[] }} opts.corpus
+ * @param {string} [opts.cwd]                 - Working directory for runner (default process.cwd()).
+ * @param {string} [opts.apiKey]              - Anthropic API key.
+ * @param {string} [opts.model]               - Model id.
+ * @param {number} [opts.maxIterations]       - Per-issue tool-loop bound.
+ * @param {boolean} [opts.dryRun]             - If true, no API calls are made.
+ * @param {{log: Function, error?: Function}} [opts.logger]
+ * @returns {Promise<object[]>}               - Array of per-run result objects.
+ */
+export async function runCorpus(opts = {}) {
+  const {
+    commandsDir,
+    corpus,
+    cwd = process.cwd(),
+    apiKey = process.env.ANTHROPIC_API_KEY,
+    model,
+    maxIterations,
+    dryRun = false,
+    logger = console,
+  } = opts;
+
+  // Lazy import of runCommand so this module stays import-safe without the SDK.
+  const { runCommand } = await import("./runner.mjs");
+
+  const results = [];
+
+  for (const issue of corpus.issues) {
+    logger.log(`[batch-runner] Starting issue #${issue}…`);
+    const startMs = Date.now();
+    let result;
+    try {
+      result = await runCommand({
+        commandsDir,
+        commandName: "work-on",
+        args: [String(issue)],
+        cwd,
+        apiKey,
+        ...(model ? { model } : {}),
+        ...(maxIterations !== undefined ? { maxIterations } : {}),
+        dryRun,
+        logger,
+      });
+      const wallClockMs = Date.now() - startMs;
+      const status = classifyRunnerResult(result);
+      results.push(
+        makeRunResult(issue, status, {
+          wallClockMs,
+          interventionCount: 0,
+          cost: null, // wired in once #1255 lands
+          iterations: result.iterations ?? null,
+          stopReason: result.stopReason ?? null,
+          model: model ?? result.model ?? null,
+          runAt: new Date().toISOString(),
+        }),
+      );
+      logger.log(`[batch-runner] Issue #${issue} → ${status} (${wallClockMs}ms)`);
+    } catch (e) {
+      const wallClockMs = Date.now() - startMs;
+      results.push(
+        makeRunResult(issue, "error", {
+          wallClockMs,
+          interventionCount: 0,
+          cost: null,
+          error: e.message,
+          model: model ?? null,
+          runAt: new Date().toISOString(),
+        }),
+      );
+      logger.error
+        ? logger.error(`[batch-runner] Issue #${issue} → error: ${e.message}`)
+        : logger.log(`[batch-runner] Issue #${issue} → error: ${e.message}`);
+    }
+  }
+
+  return results;
+}
+
+// ---------------------------------------------------------------------------
+// CLI entry point
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const [, , corpusArg, outputArg, ...flags] = process.argv;
+  const dryRun = flags.includes("--dry-run");
+
+  if (!corpusArg) {
+    process.stderr.write(
+      "Usage: node bin/batch-runner.mjs <corpus.json> [output.json] [--dry-run]\n",
+    );
+    process.exit(1);
+  }
+
+  // Resolve paths relative to cwd of the calling shell, not __dirname.
+  const corpusPath = resolve(corpusArg);
+  const outputPath = outputArg ? resolve(outputArg) : resolve("eval-results.json");
+
+  let corpus;
+  try {
+    corpus = loadCorpus(corpusPath);
+  } catch (e) {
+    process.stderr.write(`ERROR: ${e.message}\n`);
+    process.exit(1);
+  }
+
+  // commandsDir: sibling of bin/ at the repo root.
+  const { fileURLToPath } = await import("node:url");
+  const { join } = await import("node:path");
+  const binDir = dirname(fileURLToPath(import.meta.url));
+  const commandsDir = join(binDir, "..", "commands");
+
+  // Read package version for specVersion field.
+  let specVersion = null;
+  try {
+    const pkgPath = join(binDir, "..", "package.json");
+    specVersion = JSON.parse(readFileSync(pkgPath, "utf-8")).version ?? null;
+  } catch {
+    // non-fatal — specVersion stays null
+  }
+
+  console.log(
+    `[batch-runner] Running ${corpus.issues.length} issue(s) from corpus "${corpus.corpus_version ?? "(no version)"}"${dryRun ? " (dry-run)" : ""}`,
+  );
+
+  const results = await runCorpus({
+    commandsDir,
+    corpus,
+    dryRun,
+    logger: console,
+  });
+
+  const meta = {
+    corpus_version: corpus.corpus_version,
+    corpus_size: corpus.issues.length,
+    spec_version: specVersion,
+    model: results.find((r) => r.model)?.model ?? null,
+  };
+
+  writeResults(outputPath, results, meta);
+  console.log(`[batch-runner] Results written to ${outputPath}`);
+
+  const nSuccess = results.filter((r) => r.status === "success").length;
+  const nTotal = results.length;
+  console.log(`[batch-runner] ${nSuccess}/${nTotal} runs succeeded`);
+}
+
+import { fileURLToPath } from "node:url";
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  main();
+}

package/bin/cinema.mjs

@@ -0,0 +1,320 @@
+/**
+ * bin/cinema.mjs — Cinematic rendering primitives for ForgeDock's TUI.
+ *
+ * Zero-dependency. Pure presentation: gradients, the block-art F mark, and
+ * (in Task 2) shimmer / reveal / progress animation primitives.
+ *
+ * Two independent gates (spec: degradation ladder):
+ *   colorMode()     — 'truecolor' | '256' | 'none'  (NO_COLOR, TTY, TERM)
+ *   motionEnabled() — animation frames on/off        (TTY, FORGE_NO_MOTION, CI, --fast)
+ *
+ * All functions take env/stdout/argv as parameters (with process defaults)
+ * so tests never need module-cache busting.
+ */
+
+// ---------------------------------------------------------------------------
+// Palette (spec: Chrome & Ember)
+// ---------------------------------------------------------------------------
+
+export const CHROME_STOPS = ["#f7f3ea", "#d9cfba", "#a99a82", "#6e6252"];
+export const EMBER_STOPS = ["#ff4d00", "#ff8c1a", "#ffd166"];
+
+// ---------------------------------------------------------------------------
+// Gates
+// ---------------------------------------------------------------------------
+
+/**
+ * Decide the color capability of the terminal.
+ * @returns {'truecolor'|'256'|'none'}
+ */
+export function colorMode(env = process.env, stdout = process.stdout) {
+  if (stdout.isTTY !== true) return "none";
+  if (env.NO_COLOR) return "none";
+  if (env.TERM === "dumb") return "none";
+  const ct = (env.COLORTERM || "").toLowerCase();
+  if (ct.includes("truecolor") || ct.includes("24bit")) return "truecolor";
+  if ((env.TERM || "").includes("256")) return "256";
+  // Windows Terminal / modern conhost support truecolor but don't set COLORTERM.
+  if (process.platform === "win32") return "truecolor";
+  return "256";
+}
+
+/**
+ * Decide whether animation frames run. Independent of color:
+ * NO_COLOR keeps motion (monochrome choreography); non-TTY/CI/--fast kill it.
+ * @returns {boolean}
+ */
+export function motionEnabled(
+  argv = process.argv,
+  env = process.env,
+  stdout = process.stdout,
+) {
+  if (stdout.isTTY !== true) return false;
+  if (env.FORGE_NO_MOTION) return false;
+  if (env.CI) return false;
+  if (argv.includes("--fast")) return false;
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// Gradient math
+// ---------------------------------------------------------------------------
+
+function hexToRgb(hex) {
+  const h = hex.replace("#", "");
+  return [
+    parseInt(h.slice(0, 2), 16),
+    parseInt(h.slice(2, 4), 16),
+    parseInt(h.slice(4, 6), 16),
+  ];
+}
+
+/**
+ * Sample a multi-stop gradient at position t ∈ [0,1].
+ * @returns {[number, number, number]} RGB triple.
+ */
+export function sampleGradient(stops, t) {
+  const rgb = stops.map(hexToRgb);
+  const clamped = Math.min(Math.max(t, 0), 1);
+  const seg = Math.min(Math.floor(clamped * (rgb.length - 1)), rgb.length - 2);
+  const localT = clamped * (rgb.length - 1) - seg;
+  const [a, b] = [rgb[seg], rgb[seg + 1]];
+  const mix = (x, y) => Math.round(x + (y - x) * localT);
+  return [mix(a[0], b[0]), mix(a[1], b[1]), mix(a[2], b[2])];
+}
+
+/** Quantize an RGB triple to the xterm-256 6×6×6 color cube. */
+function to256([r, g, b]) {
+  const q = (v) => Math.round((v / 255) * 5);
+  return 16 + 36 * q(r) + 6 * q(g) + q(b);
+}
+
+/** Foreground escape for an RGB triple in the given mode ('' for none). */
+function fg(rgb, mode) {
+  if (mode === "none") return "";
+  if (mode === "256") return `\x1b[38;5;${to256(rgb)}m`;
+  return `\x1b[38;2;${rgb[0]};${rgb[1]};${rgb[2]}m`;
+}
+
+/**
+ * Render one line of text with a per-character horizontal gradient.
+ * Spaces stay uncolored. `phase` shifts the gradient start (for diagonals).
+ * In 'none' mode returns the input text verbatim (no reset appended).
+ */
+export function gradientLine(text, stops, mode, phase = 0) {
+  if (mode === "none") return text;
+  const chars = [...text];
+  const n = Math.max(chars.length - 1, 1);
+  let out = "";
+  for (let i = 0; i < chars.length; i++) {
+    if (chars[i] === " ") {
+      out += " ";
+      continue;
+    }
+    const t = Math.min(i / n + phase, 1);
+    out += fg(sampleGradient(stops, t), mode) + chars[i];
+  }
+  return out + "\x1b[0m";
+}
+
+/**
+ * Render a block of lines with a diagonal gradient (each row's phase shifts
+ * slightly, approximating the logo's 135° gradient).
+ * @returns {string[]}
+ */
+export function gradientBlock(lines, stops, mode) {
+  return lines.map((line, row) => gradientLine(line, stops, mode, row * 0.06));
+}
+
+// ---------------------------------------------------------------------------
+// The mark — block-art interpretation of the ForgeDock "F" (design approved
+// from the 2026-07-03 brainstorm mockups; geometry may be pixel-tuned).
+// ---------------------------------------------------------------------------
+
+export const HERO_MARK = [
+  "            ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄",
+  "        ▄▄██████████████████",
+  "     ▄█████████████▀▀▀▀▀▀▀▀▀",
+  "   ▄██████████▀▀",
+  "    ▀▀▀▀▀  ▄▄███████▀",
+  "        ▄████████▀",
+  "      ▄██████▀",
+  "       ▀▀▀▀",
+];
+
+export const COMPACT_MARK = [
+  "   ▄▄████████",
+  " ▄█████▀▀▀▀▀",
+  " ▀▀ ▄████▀",
+  "   ▀▀▀",
+];
+
+/**
+ * Render the chrome-gradient mark.
+ * @param {'hero'|'compact'} size
+ * @param {'truecolor'|'256'|'none'} mode
+ * @returns {string[]}
+ */
+export function renderMark(size, mode) {
+  const art = size === "hero" ? HERO_MARK : COMPACT_MARK;
+  if (mode === "none") return [...art];
+  return gradientBlock(art, CHROME_STOPS, mode);
+}
+
+/** Ember-gradient text shorthand (wordmarks, act headers). */
+export function ember(text, mode) {
+  return gradientLine(text, EMBER_STOPS, mode);
+}
+
+/** Promise-based sleep for animation pacing. */
+export function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+// ---------------------------------------------------------------------------
+// Animation primitives (Task 2)
+// ---------------------------------------------------------------------------
+
+import { box } from "./tui.mjs";
+
+const BRAILLE = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+/** Ember-tinted status glyph for a result row. */
+function statusGlyph(ok, mode) {
+  const rgb = ok ? [255, 179, 71] : [224, 112, 80]; // amber / ember-red
+  const glyph = ok ? "✔" : "✖";
+  if (mode === "none") return glyph;
+  return `${fg(rgb, mode)}${glyph}\x1b[0m`;
+}
+
+/** Dim wrapper honoring the mode gate. */
+function dimText(s, mode) {
+  return mode === "none" ? s : `\x1b[2m${s}\x1b[22m`;
+}
+
+/** Badge like [high] / [med] / [low], colorized per confidence. */
+function badgeText(badge, mode) {
+  const label = badge === "medium" ? "med" : badge;
+  if (mode === "none") return `[${label}]`;
+  const rgb = badge === "high" ? [125, 219, 132] : badge === "medium" ? [232, 192, 96] : [224, 112, 80];
+  return `${fg(rgb, mode)}[${label}]\x1b[0m`;
+}
+
+/** Ember-bordered fix card (wraps tui.box; border color applied when able). */
+export function fixCard(lines, mode) {
+  const boxed = box(lines.map((l) => ` ${l} `), { title: "fix" });
+  if (mode === "none") return boxed;
+  const ember = fg([255, 107, 53], mode);
+  return boxed
+    .split("\n")
+    .map((l) => l.replace(/[╭╮╰╯─│]/gu, (m) => `${ember}${m}\x1b[0m`))
+    .join("\n");
+}
+
+function formatRow(label, res, mode) {
+  const parts = [`  ${statusGlyph(res.ok, mode)} ${label.padEnd(16)}`];
+  if (res.detail) parts.push(dimText(String(res.detail), mode));
+  if (res.badge) parts.push(badgeText(res.badge, mode));
+  return parts.join("  ");
+}
+
+/**
+ * Reveal rows one at a time: spinner while `run()` is in flight, settling to
+ * a ✔/✖ line (+ optional fix card). Without motion: run, print final line.
+ * Every row's `run` executes regardless of motion — this is display-only.
+ */
+export async function revealRows(
+  rows,
+  { mode, motion, writer = process.stdout, interval = 80, minDisplayMs = 120 } = {},
+) {
+  const results = [];
+  for (const row of rows) {
+    let res;
+    if (!motion) {
+      res = await row.run();
+    } else {
+      let frame = 0;
+      const spinnerColor = fg([255, 107, 53], mode);
+      const reset = mode === "none" ? "" : "\x1b[0m";
+      writer.write(`  ${spinnerColor}${BRAILLE[0]}${reset} ${row.label}\n`);
+      const timer = setInterval(() => {
+        frame = (frame + 1) % BRAILLE.length;
+        writer.write(`\x1b[1A\x1b[2K  ${spinnerColor}${BRAILLE[frame]}${reset} ${row.label}\n`);
+      }, interval);
+      const started = Date.now();
+      try {
+        res = await row.run();
+        const elapsed = Date.now() - started;
+        if (elapsed < minDisplayMs) await sleep(minDisplayMs - elapsed);
+      } finally {
+        clearInterval(timer);
+      }
+      writer.write("\x1b[1A\x1b[2K");
+    }
+    writer.write(formatRow(row.label, res, mode) + "\n");
+    if (!res.ok && res.fix && res.fix.length > 0) {
+      writer.write(fixCard(res.fix, mode) + "\n");
+    }
+    results.push(res);
+  }
+  return results;
+}
+
+/**
+ * One-pass highlight sweep over gradient block art, settling to the static
+ * gradientBlock render. In-place redraw via cursor-up; never alt-screen.
+ */
+export async function shimmer(
+  lines,
+  stops,
+  { mode, motion, writer = process.stdout, frames = 14, interval = 55 } = {},
+) {
+  const settled = gradientBlock(lines, stops, mode);
+  if (!motion || mode === "none") {
+    writer.write(settled.join("\n") + "\n");
+    return;
+  }
+  const width = Math.max(...lines.map((l) => l.length));
+  for (let f = 0; f <= frames; f++) {
+    const band = (f / frames) * (width + 16) - 8;
+    const frameLines = lines.map((line, row) => {
+      const chars = [...line];
+      let out = "";
+      for (let i = 0; i < chars.length; i++) {
+        if (chars[i] === " ") {
+          out += " ";
+          continue;
+        }
+        const t = Math.min(i / Math.max(chars.length - 1, 1) + row * 0.06, 1);
+        let rgb = sampleGradient(stops, t);
+        const dist = Math.abs(i - band + row * 1.5);
+        if (dist < 6) {
+          const boost = 1 - dist / 6;
+          rgb = rgb.map((v) => Math.round(v + (255 - v) * boost));
+        }
+        out += `\x1b[38;2;${rgb[0]};${rgb[1]};${rgb[2]}m${chars[i]}`;
+      }
+      return out + "\x1b[0m";
+    });
+    if (f > 0) writer.write(`\x1b[${lines.length}A`);
+    writer.write(frameLines.join("\n") + "\n");
+    await sleep(interval);
+  }
+  writer.write(`\x1b[${lines.length}A`);
+  writer.write(settled.join("\n") + "\n");
+}
+
+/**
+ * One static frame of the molten progress bar: solid fill with a ▓▒ leading
+ * edge and dim ░ remainder. Caller redraws with cursor-up for animation.
+ */
+export function moltenBar(current, total, { width = 24, mode } = {}) {
+  const ratio = total === 0 ? 1 : Math.min(current / total, 1);
+  const filled = Math.round(ratio * width);
+  const solidLen = Math.max(filled - 2, 0);
+  const edge = "▓▒".slice(0, filled - solidLen);
+  const body = "█".repeat(solidLen) + edge;
+  const rest = "░".repeat(Math.max(width - filled, 0));
+  if (mode === "none") return `[${body}${rest}]`;
+  return gradientLine(body, EMBER_STOPS, mode) + dimText(rest, mode);
+}