@zhijiewang/openharness 2.38.0 → 2.40.0

package/dist/evals/run-writer.js

@@ -0,0 +1,94 @@
+/**
+ * oh evals — run writer.
+ *
+ * Streams per-task results to disk atomically:
+ *  - results.jsonl   : append-only, one EvalsResult per line
+ *  - predictions.json: array, rewritten on each append, SWE-bench-submittable
+ *  - results.json    : merged + aggregates, written ONLY by finalize()
+ *
+ * Crash-safety: results.jsonl + predictions.json are valid up to the last
+ * successful append. `oh evals run --resume <run_id>` reads results.jsonl
+ * to determine completed instance_ids.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+export class RunWriter {
+    runDir;
+    header;
+    results = [];
+    constructor(runDir, header) {
+        this.runDir = runDir;
+        this.header = header;
+        mkdirSync(runDir, { recursive: true });
+        mkdirSync(join(runDir, "transcripts"), { recursive: true });
+    }
+    appendResult(result) {
+        this.results.push(result);
+        // results.jsonl — append a single line atomically.
+        const line = `${JSON.stringify(result)}\n`;
+        appendFileSync(join(this.runDir, "results.jsonl"), line);
+        // predictions.json — rewrite the array atomically (.tmp → rename).
+        const preds = this.results.map((r) => ({
+            instance_id: r.instance_id,
+            model_patch: r.model_patch,
+            model_name_or_path: this.header.model,
+        }));
+        const tmp = join(this.runDir, "predictions.json.tmp");
+        writeFileSync(tmp, JSON.stringify(preds, null, 2));
+        renameSync(tmp, join(this.runDir, "predictions.json"));
+    }
+    loadExistingResults() {
+        const path = join(this.runDir, "results.jsonl");
+        if (!existsSync(path))
+            return [];
+        return readFileSync(path, "utf-8")
+            .split("\n")
+            .filter((l) => l.trim().length > 0)
+            .map((l) => JSON.parse(l));
+    }
+    finalize(opts) {
+        const counts = {
+            resolved: 0,
+            failed: 0,
+            error: 0,
+            timeout: 0,
+            budget_exceeded: 0,
+            skipped: 0,
+        };
+        let totalCost = 0;
+        let totalDuration = 0;
+        for (const r of this.results) {
+            counts[r.status]++;
+            totalCost += r.cost_usd;
+            totalDuration += r.duration_ms;
+        }
+        const denom = counts.resolved + counts.failed + counts.error + counts.timeout;
+        const passRate = denom === 0 ? 0 : counts.resolved / denom;
+        const artifacts = {
+            run_id: this.header.run_id,
+            pack: this.header.pack,
+            pack_version: this.header.pack_version,
+            model: this.header.model,
+            harness_version: this.header.harness_version,
+            started_at: this.header.started_at,
+            finished_at: opts.finished_at,
+            total_cost_usd: totalCost,
+            max_cost_usd: this.header.max_cost_usd,
+            total_duration_ms: totalDuration,
+            resolved: counts.resolved,
+            failed: counts.failed,
+            error: counts.error,
+            timeout: counts.timeout,
+            budget_exceeded: counts.budget_exceeded,
+            skipped: counts.skipped,
+            pass_rate: passRate,
+            partial: opts.partial,
+            results: [...this.results],
+        };
+        const tmp = join(this.runDir, "results.json.tmp");
+        writeFileSync(tmp, JSON.stringify(artifacts, null, 2));
+        renameSync(tmp, join(this.runDir, "results.json"));
+        return artifacts;
+    }
+}
+//# sourceMappingURL=run-writer.js.map

package/dist/evals/scorer.d.ts

@@ -0,0 +1,34 @@
+/**
+ * oh evals — scorer.
+ *
+ * After the agent runs, we score the task by:
+ *  (1) Running an oracle script (oracle.sh / oracle.mjs) if one exists in
+ *      the fixture dir — exit 0 = pass.
+ *  (2) Else running the pack's default test command and parsing the
+ *      junit-xml output for FAIL_TO_PASS / PASS_TO_PASS test IDs.
+ *
+ * Test ID convention matches SWE-bench: "<classname>.<name>".
+ */
+import type { EvalsTask, TestsStatus } from "./types.js";
+export type TestOutcome = "pass" | "fail" | "skip";
+/**
+ * Minimal junit-xml parser. Returns a map of "<classname>.<name>" → outcome.
+ *
+ * We don't take a full XML parser dependency; pytest's junit-xml is
+ * well-formed and simple enough to extract testcase elements with regex.
+ */
+export declare function parseJunitXml(xml: string): Record<string, TestOutcome>;
+export type ScoreResult = {
+    resolved: boolean;
+    tests_status: TestsStatus;
+    oracle_used: boolean;
+    error_message?: string;
+};
+export declare function scoreTask(args: {
+    task: EvalsTask;
+    worktreeDir: string;
+    fixtureDir: string;
+    packDefaultTestCommand: string;
+    testTimeoutMs: number;
+}): Promise<ScoreResult>;
+//# sourceMappingURL=scorer.d.ts.map

package/dist/evals/scorer.js

@@ -0,0 +1,127 @@
+/**
+ * oh evals — scorer.
+ *
+ * After the agent runs, we score the task by:
+ *  (1) Running an oracle script (oracle.sh / oracle.mjs) if one exists in
+ *      the fixture dir — exit 0 = pass.
+ *  (2) Else running the pack's default test command and parsing the
+ *      junit-xml output for FAIL_TO_PASS / PASS_TO_PASS test IDs.
+ *
+ * Test ID convention matches SWE-bench: "<classname>.<name>".
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * Minimal junit-xml parser. Returns a map of "<classname>.<name>" → outcome.
+ *
+ * We don't take a full XML parser dependency; pytest's junit-xml is
+ * well-formed and simple enough to extract testcase elements with regex.
+ */
+export function parseJunitXml(xml) {
+    const out = {};
+    const testcaseRe = /<testcase\b([^>]*?)(?:\/>|>([\s\S]*?)<\/testcase>)/g;
+    let match = testcaseRe.exec(xml);
+    while (match !== null) {
+        const attrs = match[1];
+        const inner = match[2] ?? "";
+        const cn = /classname="([^"]*)"/.exec(attrs)?.[1];
+        const name = /\bname="([^"]*)"/.exec(attrs)?.[1];
+        if (cn && name) {
+            const id = `${cn}.${name}`;
+            if (/<failure\b/.test(inner) || /<error\b/.test(inner)) {
+                out[id] = "fail";
+            }
+            else if (/<skipped\b/.test(inner)) {
+                out[id] = "skip";
+            }
+            else {
+                out[id] = "pass";
+            }
+        }
+        match = testcaseRe.exec(xml);
+    }
+    return out;
+}
+const EMPTY_TESTS_STATUS = {
+    FAIL_TO_PASS: { success: [], failure: [] },
+    PASS_TO_PASS: { success: [], failure: [] },
+};
+export async function scoreTask(args) {
+    const { task, worktreeDir, fixtureDir, packDefaultTestCommand, testTimeoutMs } = args;
+    // (1) Oracle escape hatch.
+    const oracleSh = join(fixtureDir, "oracle.sh");
+    const oracleMjs = join(fixtureDir, "oracle.mjs");
+    if (existsSync(oracleSh)) {
+        const r = spawnSync(oracleSh, [], {
+            cwd: worktreeDir,
+            env: {
+                ...process.env,
+                INSTANCE_ID: task.instance_id,
+                WORKTREE_DIR: worktreeDir,
+                FIXTURE_DIR: fixtureDir,
+            },
+            timeout: testTimeoutMs,
+            shell: process.platform === "win32",
+        });
+        return {
+            resolved: r.status === 0,
+            tests_status: EMPTY_TESTS_STATUS,
+            oracle_used: true,
+            error_message: r.status === 0 ? undefined : (r.stderr?.toString().slice(-500) ?? ""),
+        };
+    }
+    if (existsSync(oracleMjs)) {
+        const r = spawnSync(process.execPath, [oracleMjs], {
+            cwd: worktreeDir,
+            env: {
+                ...process.env,
+                INSTANCE_ID: task.instance_id,
+                WORKTREE_DIR: worktreeDir,
+                FIXTURE_DIR: fixtureDir,
+            },
+            timeout: testTimeoutMs,
+        });
+        return {
+            resolved: r.status === 0,
+            tests_status: EMPTY_TESTS_STATUS,
+            oracle_used: true,
+            error_message: r.status === 0 ? undefined : (r.stderr?.toString().slice(-500) ?? ""),
+        };
+    }
+    // (2) Default test command.
+    const r = spawnSync(packDefaultTestCommand, {
+        cwd: worktreeDir,
+        shell: true,
+        timeout: testTimeoutMs,
+    });
+    const xmlPath = join(worktreeDir, ".oh-evals-results.xml");
+    if (!existsSync(xmlPath)) {
+        return {
+            resolved: false,
+            tests_status: structuredClone(EMPTY_TESTS_STATUS),
+            oracle_used: false,
+            error_message: `junit-xml not produced at ${xmlPath} (test command exit ${r.status}). stderr: ${r.stderr?.toString().slice(-500) ?? ""}`,
+        };
+    }
+    const outcomes = parseJunitXml(readFileSync(xmlPath, "utf-8"));
+    const tests_status = {
+        FAIL_TO_PASS: { success: [], failure: [] },
+        PASS_TO_PASS: { success: [], failure: [] },
+    };
+    for (const id of task.FAIL_TO_PASS) {
+        if (outcomes[id] === "pass")
+            tests_status.FAIL_TO_PASS.success.push(id);
+        else
+            tests_status.FAIL_TO_PASS.failure.push(id);
+    }
+    for (const id of task.PASS_TO_PASS) {
+        if (outcomes[id] === "pass")
+            tests_status.PASS_TO_PASS.success.push(id);
+        else
+            tests_status.PASS_TO_PASS.failure.push(id);
+    }
+    const resolved = tests_status.FAIL_TO_PASS.failure.length === 0 && tests_status.PASS_TO_PASS.failure.length === 0;
+    return { resolved, tests_status, oracle_used: false };
+}
+//# sourceMappingURL=scorer.js.map

package/dist/evals/types.d.ts

@@ -0,0 +1,74 @@
+/**
+ * oh evals — type definitions for the eval harness.
+ *
+ * Schema mirrors SWE-bench's evaluation contract so packs of cherry-picked
+ * SWE-bench Lite instances drop in unmodified. Our `EvalsResult` is a
+ * superset of SWE-bench's `results.json` per-instance shape, with cost,
+ * turns, duration, and transcript-path enrichments.
+ */
+export type EvalsTask = {
+    instance_id: string;
+    repo: string;
+    base_commit: string;
+    problem_statement: string;
+    FAIL_TO_PASS: string[];
+    PASS_TO_PASS: string[];
+    hints_text?: string;
+};
+export type EvalsPack = {
+    name: string;
+    version: string;
+    description: string;
+    language: "python" | "javascript" | "typescript" | "polyglot";
+    runner_requirements: string[];
+    default_test_command: string;
+    instance_count: number;
+    compatible_with?: string;
+};
+export type EvalsStatus = "resolved" | "failed" | "error" | "timeout" | "budget_exceeded" | "skipped";
+export type TestsStatus = {
+    FAIL_TO_PASS: {
+        success: string[];
+        failure: string[];
+    };
+    PASS_TO_PASS: {
+        success: string[];
+        failure: string[];
+    };
+};
+export type EvalsResult = {
+    instance_id: string;
+    status: EvalsStatus;
+    resolved: boolean;
+    cost_usd: number;
+    turns_used: number;
+    duration_ms: number;
+    model_patch: string;
+    tests_status: TestsStatus;
+    transcript_path: string;
+    error_message?: string;
+    started_at: string;
+    finished_at: string;
+};
+export type RunArtifacts = {
+    run_id: string;
+    pack: string;
+    pack_version: string;
+    model: string;
+    harness_version: string;
+    started_at: string;
+    finished_at: string;
+    total_cost_usd: number;
+    max_cost_usd: number;
+    total_duration_ms: number;
+    resolved: number;
+    failed: number;
+    error: number;
+    timeout: number;
+    budget_exceeded: number;
+    skipped: number;
+    pass_rate: number;
+    partial: boolean;
+    results: EvalsResult[];
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/evals/types.js

@@ -0,0 +1,10 @@
+/**
+ * oh evals — type definitions for the eval harness.
+ *
+ * Schema mirrors SWE-bench's evaluation contract so packs of cherry-picked
+ * SWE-bench Lite instances drop in unmodified. Our `EvalsResult` is a
+ * superset of SWE-bench's `results.json` per-instance shape, with cost,
+ * turns, duration, and transcript-path enrichments.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/harness/sandbox.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Sandbox — filesystem and network restrictions for tool execution.
+ *
+ * Limits what tools can access:
+ * - File tools: only write to allowed paths
+ * - Web tools: only access allowed domains
+ * - Bash: restricted commands (no curl/wget by default)
+ *
+ * Reduces permission prompts while maintaining security.
+ */
+export type SandboxConfig = {
+    enabled: boolean;
+    /** Paths tools can write to (glob-style, relative to cwd) */
+    allowedPaths: string[];
+    /** Domains WebFetch/WebSearch can access */
+    allowedDomains: string[];
+    /** Block all network access */
+    blockNetwork: boolean;
+    /** Commands blocked in Bash (default: curl, wget) */
+    blockedCommands: string[];
+};
+/** Get the current sandbox config */
+export declare function getSandboxConfig(): SandboxConfig;
+/** Reset cached config */
+export declare function invalidateSandboxCache(): void;
+/** Check if a file path is allowed for writing */
+export declare function isPathAllowed(filePath: string): boolean;
+/** Check if a domain is allowed for network access */
+export declare function isDomainAllowed(url: string): boolean;
+/** Check if a bash command is allowed */
+export declare function isCommandAllowed(command: string): boolean;
+/** Get a human-readable sandbox status */
+export declare function sandboxStatus(): string;
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/harness/sandbox.js

@@ -0,0 +1,104 @@
+/**
+ * Sandbox — filesystem and network restrictions for tool execution.
+ *
+ * Limits what tools can access:
+ * - File tools: only write to allowed paths
+ * - Web tools: only access allowed domains
+ * - Bash: restricted commands (no curl/wget by default)
+ *
+ * Reduces permission prompts while maintaining security.
+ */
+import { relative, resolve } from "node:path";
+import { readOhConfig } from "./config.js";
+const DEFAULT_SANDBOX = {
+    enabled: false,
+    allowedPaths: ["."], // current directory
+    allowedDomains: [], // empty = all allowed
+    blockNetwork: false,
+    blockedCommands: ["curl", "wget"],
+};
+// ── Sandbox Manager ──
+let _config = null;
+/** Get the current sandbox config */
+export function getSandboxConfig() {
+    if (_config)
+        return _config;
+    const ohConfig = readOhConfig();
+    if (ohConfig?.sandbox) {
+        _config = {
+            ...DEFAULT_SANDBOX,
+            ...ohConfig.sandbox,
+        };
+    }
+    else {
+        _config = DEFAULT_SANDBOX;
+    }
+    return _config;
+}
+/** Reset cached config */
+export function invalidateSandboxCache() {
+    _config = null;
+}
+/** Check if a file path is allowed for writing */
+export function isPathAllowed(filePath) {
+    const config = getSandboxConfig();
+    if (!config.enabled)
+        return true;
+    const resolved = resolve(filePath);
+    const cwd = process.cwd();
+    for (const allowed of config.allowedPaths) {
+        const allowedResolved = resolve(cwd, allowed);
+        // Check if the file is within the allowed directory
+        const rel = relative(allowedResolved, resolved);
+        if (!rel.startsWith("..") && !rel.startsWith("/"))
+            return true;
+    }
+    return false;
+}
+/** Check if a domain is allowed for network access */
+export function isDomainAllowed(url) {
+    const config = getSandboxConfig();
+    if (!config.enabled)
+        return true;
+    if (config.blockNetwork)
+        return false;
+    if (config.allowedDomains.length === 0)
+        return true;
+    try {
+        const hostname = new URL(url).hostname.toLowerCase();
+        return config.allowedDomains.some((d) => hostname === d.toLowerCase() || hostname.endsWith(`.${d.toLowerCase()}`));
+    }
+    catch {
+        return false;
+    }
+}
+/** Check if a bash command is allowed */
+export function isCommandAllowed(command) {
+    const config = getSandboxConfig();
+    if (!config.enabled)
+        return true;
+    const firstWord = command.trim().split(/\s+/)[0]?.toLowerCase() ?? "";
+    return !config.blockedCommands.includes(firstWord);
+}
+/** Get a human-readable sandbox status */
+export function sandboxStatus() {
+    const config = getSandboxConfig();
+    if (!config.enabled)
+        return "Sandbox: disabled";
+    const lines = ["Sandbox: enabled"];
+    lines.push(`  Allowed paths: ${config.allowedPaths.join(", ") || "none"}`);
+    if (config.blockNetwork) {
+        lines.push("  Network: blocked");
+    }
+    else if (config.allowedDomains.length > 0) {
+        lines.push(`  Allowed domains: ${config.allowedDomains.join(", ")}`);
+    }
+    else {
+        lines.push("  Network: unrestricted");
+    }
+    if (config.blockedCommands.length > 0) {
+        lines.push(`  Blocked commands: ${config.blockedCommands.join(", ")}`);
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=sandbox.js.map

package/dist/harness/traces.d.ts

@@ -83,6 +83,31 @@ export declare function loadTrace(sessionId: string): TraceSpan[];
 export declare function listTracedSessions(): string[];
 /** Format trace for display */
 export declare function formatTrace(spans: TraceSpan[]): string;
+/**
+ * Render spans as a flame-graph (icicle-graph really — top-down by depth).
+ * Each span gets one row: indent by tree depth, then a bar of `█` characters
+ * positioned along a wall-time axis sized to `width` columns. Bars start at
+ * the column corresponding to the span's `startTime` relative to the trace's
+ * minimum startTime, and span as many columns as their `durationMs` requires
+ * (minimum 1 column so even sub-millisecond spans are visible).
+ *
+ * Total trace duration sets the time-axis scale: a 5-second trace and a
+ * 50-second trace both fit the same `width`, so the same view works at any
+ * scale without scrolling. Per-span ms label appears to the right of the bar;
+ * span name appears at the left, indented by parent depth.
+ *
+ * Errored spans (status: "error") render in red; others use a stable
+ * per-name color so the same tool keeps the same color across the trace.
+ *
+ * The bottom row is a time ruler with ticks at 0ms, 25%, 50%, 75%, 100%.
+ *
+ * @param spans the spans to render — typically `loadTrace(sessionId)`
+ * @param width target width in columns (defaults to terminal width or 100)
+ * @param opts.color emit ANSI color codes (defaults to true; set false for tests)
+ */
+export declare function formatFlameGraph(spans: TraceSpan[], width?: number, opts?: {
+    color?: boolean;
+}): string;
 /** Export trace in OpenTelemetry-compatible format */
 export declare function exportTraceOTLP(sessionId: string, spans: TraceSpan[]): object;
 //# sourceMappingURL=traces.d.ts.map

package/dist/harness/traces.js

@@ -220,6 +220,174 @@ export function formatTrace(spans) {
     lines.push(`Total: ${spans.length} spans, ${totalMs}ms, ${errors} errors`);
     return lines.join("\n");
 }
+// ── Flame-graph rendering ──
+/** ANSI 256 colors picked for distinguishability across span names. */
+const FLAME_COLORS = [
+    "\x1b[38;5;202m", // orange (query)
+    "\x1b[38;5;39m", // light blue (tool:Read)
+    "\x1b[38;5;208m", // bright orange (tool:Bash)
+    "\x1b[38;5;105m", // purple (tool:Edit)
+    "\x1b[38;5;118m", // green (tool:Glob/Grep)
+    "\x1b[38;5;226m", // yellow (tool:Web*)
+    "\x1b[38;5;213m", // pink (think tools)
+    "\x1b[38;5;245m", // grey (other)
+];
+const ANSI_RESET = "\x1b[0m";
+const ANSI_DIM = "\x1b[2m";
+const ANSI_RED = "\x1b[38;5;196m";
+function colorForSpan(name) {
+    // Stable hash so the same span name always lands the same color across renders.
+    let hash = 0;
+    for (let i = 0; i < name.length; i++)
+        hash = (hash * 31 + name.charCodeAt(i)) >>> 0;
+    return FLAME_COLORS[hash % FLAME_COLORS.length];
+}
+/**
+ * Render spans as a flame-graph (icicle-graph really — top-down by depth).
+ * Each span gets one row: indent by tree depth, then a bar of `█` characters
+ * positioned along a wall-time axis sized to `width` columns. Bars start at
+ * the column corresponding to the span's `startTime` relative to the trace's
+ * minimum startTime, and span as many columns as their `durationMs` requires
+ * (minimum 1 column so even sub-millisecond spans are visible).
+ *
+ * Total trace duration sets the time-axis scale: a 5-second trace and a
+ * 50-second trace both fit the same `width`, so the same view works at any
+ * scale without scrolling. Per-span ms label appears to the right of the bar;
+ * span name appears at the left, indented by parent depth.
+ *
+ * Errored spans (status: "error") render in red; others use a stable
+ * per-name color so the same tool keeps the same color across the trace.
+ *
+ * The bottom row is a time ruler with ticks at 0ms, 25%, 50%, 75%, 100%.
+ *
+ * @param spans the spans to render — typically `loadTrace(sessionId)`
+ * @param width target width in columns (defaults to terminal width or 100)
+ * @param opts.color emit ANSI color codes (defaults to true; set false for tests)
+ */
+export function formatFlameGraph(spans, width = process.stdout.columns || 100, opts = {}) {
+    if (spans.length === 0)
+        return "No trace spans recorded.";
+    const useColor = opts.color !== false;
+    const c = (style, text) => (useColor ? `${style}${text}${ANSI_RESET}` : text);
+    // Trace bounds — every other timestamp is relative to minStart.
+    let minStart = Infinity;
+    let maxEnd = 0;
+    for (const s of spans) {
+        if (s.startTime < minStart)
+            minStart = s.startTime;
+        if (s.endTime > maxEnd)
+            maxEnd = s.endTime;
+    }
+    const totalMs = maxEnd > minStart ? maxEnd - minStart : 1;
+    // Layout: name column gets up to 30 chars; ms label gets up to 10; the rest
+    // is the bar canvas. We need at least ~20 cols of bar canvas to be useful.
+    const NAME_WIDTH = 30;
+    const MS_WIDTH = 10;
+    const PADDING = 3; // spaces between sections
+    const barWidth = Math.max(20, width - NAME_WIDTH - MS_WIDTH - PADDING);
+    // Build the depth map by walking the parent chain (spans are typically in
+    // start-order but we don't rely on it). Caps recursion to prevent infinite
+    // loops on a malformed trace where parent references form a cycle.
+    const byId = new Map(spans.map((s) => [s.spanId, s]));
+    const depthOf = new Map();
+    function depth(span, hops = 0) {
+        if (hops > 50)
+            return hops;
+        if (depthOf.has(span.spanId))
+            return depthOf.get(span.spanId);
+        let d = 0;
+        if (span.parentSpanId) {
+            const parent = byId.get(span.parentSpanId);
+            if (parent)
+                d = depth(parent, hops + 1) + 1;
+        }
+        depthOf.set(span.spanId, d);
+        return d;
+    }
+    for (const s of spans)
+        depth(s);
+    // Sort by start time, ties broken by depth (parents before children).
+    const sorted = [...spans].sort((a, b) => a.startTime - b.startTime || depthOf.get(a.spanId) - depthOf.get(b.spanId));
+    const lines = [];
+    for (const span of sorted) {
+        const d = depthOf.get(span.spanId);
+        const offset = Math.floor(((span.startTime - minStart) / totalMs) * barWidth);
+        const length = Math.max(1, Math.floor((span.durationMs / totalMs) * barWidth));
+        const indent = "  ".repeat(Math.min(d, 4)); // visual cap at 4 indent levels
+        const name = `${indent}${span.name}`.padEnd(NAME_WIDTH).slice(0, NAME_WIDTH);
+        const bar = " ".repeat(offset) + "█".repeat(Math.min(length, barWidth - offset));
+        const paddedBar = bar.padEnd(barWidth);
+        const color = span.status === "error" ? ANSI_RED : colorForSpan(span.name);
+        const msLabel = `${span.durationMs}ms`.padStart(MS_WIDTH);
+        lines.push(`${name}   ${c(color, paddedBar)} ${c(ANSI_DIM, msLabel)}`);
+    }
+    // Time ruler: 3-5 ticks depending on canvas width. We need ~8 columns per
+    // tick to fit timestamp labels without overlap; choose count that fits.
+    const tickCount = barWidth >= 50 ? 5 : barWidth >= 30 ? 3 : 2;
+    const tickPcts = [];
+    for (let i = 0; i < tickCount; i++)
+        tickPcts.push(i / (tickCount - 1));
+    const tickValues = tickPcts.map((pct) => `${Math.round(totalMs * pct)}ms`);
+    const rulerLine = " ".repeat(NAME_WIDTH + 3) + buildTimeRuler(barWidth, tickValues);
+    lines.push("");
+    lines.push(c(ANSI_DIM, rulerLine));
+    // Per-name summary: count + total ms, descending by total ms.
+    const summary = {};
+    for (const s of spans) {
+        const e = summary[s.name] ?? { count: 0, totalMs: 0 };
+        e.count++;
+        e.totalMs += s.durationMs;
+        summary[s.name] = e;
+    }
+    const ranked = Object.entries(summary).sort((a, b) => b[1].totalMs - a[1].totalMs);
+    lines.push("");
+    lines.push(c(ANSI_DIM, "Span breakdown (top by total time):"));
+    for (const [name, { count, totalMs: tms }] of ranked.slice(0, 10)) {
+        const pct = totalMs > 0 ? Math.round((tms / totalMs) * 100) : 0;
+        lines.push(`  ${c(colorForSpan(name), "█")} ${name.padEnd(28)} ${count.toString().padStart(4)}× ${tms.toString().padStart(6)}ms  ${pct}%`);
+    }
+    const errors = spans.filter((s) => s.status === "error").length;
+    lines.push("");
+    lines.push(c(ANSI_DIM, `${spans.length} spans, ${totalMs}ms total${errors > 0 ? `, ${errors} error(s)` : ""}`));
+    return lines.join("\n");
+}
+/**
+ * Build a time ruler line of exactly `width` columns with N tick labels
+ * distributed evenly. Strategy: anchor the last tick right-aligned to the
+ * width, then place earlier ticks at their proportional positions while
+ * truncating any label that would overlap the next tick (or the last
+ * tick's reserved start). Produces a clean ruler at any (width × N).
+ *
+ * The last tick's right-anchor means the rightmost timestamp always lands
+ * exactly at the canvas edge, matching where bars end.
+ */
+function buildTimeRuler(width, ticks) {
+    if (ticks.length === 0 || width <= 0)
+        return "";
+    const buf = new Array(width).fill(" ");
+    // Step 1: place last tick right-aligned. Its start column constrains all
+    // earlier ticks (they must end before lastStart - 1 so there's a gap).
+    const lastLabel = ticks[ticks.length - 1];
+    const lastStart = Math.max(0, width - lastLabel.length);
+    for (let j = 0; j < lastLabel.length && lastStart + j < width; j++) {
+        buf[lastStart + j] = lastLabel[j];
+    }
+    // Step 2: place earlier ticks left-to-right. Each can occupy from its
+    // proportional start column up to either the next tick's start (minus 1
+    // for a separator space) or, for the second-to-last tick, lastStart - 1.
+    for (let i = 0; i < ticks.length - 1; i++) {
+        const label = ticks[i];
+        const start = Math.round((i / (ticks.length - 1)) * (width - 1));
+        const nextProportional = Math.round(((i + 1) / (ticks.length - 1)) * (width - 1));
+        const isPenultimate = i === ticks.length - 2;
+        const endExclusive = isPenultimate ? lastStart - 1 : nextProportional - 1;
+        const maxLen = Math.max(0, endExclusive - start);
+        const out = label.slice(0, maxLen);
+        for (let j = 0; j < out.length; j++)
+            buf[start + j] = out[j];
+    }
+    return buf.join("");
+}
 /**
  * Coerce an arbitrary string (UUID with hyphens, "span-N", etc.) into a fixed-length
  * lowercase hex string suitable for OTLP. OTLP collectors (Jaeger, Tempo, OTel