glm-coding-router 1.1.2 → 2.0.0

package/dist/budget/manager.js

@@ -0,0 +1,223 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fetchZaiQuota } from "../core/zai-quota.js";
+import { logger } from "../core/logging.js";
+import { quotaCachePath } from "../core/paths.js";
+/** Same TTL as the shipped config default; callers pass routing.quotaCacheTtlSec. */
+const DEFAULT_TTL_SEC = 60;
+const ZERO_WINDOW = {
+    used: 0,
+    limit: 0,
+    remaining: 0,
+    remainingRatio: 0,
+    resetAt: null,
+};
+/**
+ * Maps one CREDIT_LIMIT entry onto a BudgetWindow. The server's `remaining`
+ * is authoritative even though the real payload does not add up
+ * (912 + 1087 = 1999 of 2000) — recomputing it would silently change the
+ * number routing decides on. `limit - used` is only a fallback for when the
+ * server omits `remaining` entirely.
+ */
+function windowFrom(limit) {
+    if (limit === undefined) {
+        return ZERO_WINDOW;
+    }
+    const limitValue = finiteNumber(limit.usage) ?? 0;
+    const used = finiteNumber(limit.currentValue) ?? 0;
+    const remaining = finiteNumber(limit.remaining) ?? limitValue - used;
+    return {
+        used,
+        limit: limitValue,
+        remaining,
+        // 0 — never NaN, never Infinity — when the limit is 0 or missing, so the
+        // ratio math downstream (zoneFor, the Phase E router) stays finite no
+        // matter what the endpoint reports.
+        remainingRatio: limitValue > 0 ? remaining / limitValue : 0,
+        resetAt: typeof limit.nextResetTime === "number" && Number.isFinite(limit.nextResetTime)
+            ? new Date(limit.nextResetTime).toISOString()
+            : null,
+    };
+}
+function finiteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+/**
+ * Window mapping verified live (specs/usage.md): `unit 3` is the 5-hour
+ * window, `unit 6 & number 1` the weekly one. Other entries are windows this
+ * build does not route on and are ignored.
+ */
+function snapshotFrom(data, fetchedAt) {
+    const limits = Array.isArray(data.limits) ? data.limits : [];
+    const fiveHour = limits.find((limit) => limit.unit === 3);
+    const weekly = limits.find((limit) => limit.unit === 6 && limit.number === 1);
+    // Fail-open has a side door, and this closes it. A 200 response that carries
+    // neither window is a real state of this endpoint, not a hypothetical —
+    // `usage.ts` already renders "(no quota windows reported)" for it. Mapped
+    // naively it becomes an "exact" all-zero snapshot, which zoneFor reads as
+    // CRITICAL: every run downgraded and warned today, every run refused once
+    // refuseOnCritical flips in 2.1 — on a payload that told us nothing at all.
+    // A window we cannot see is unknown, never empty. Both are required because
+    // the router reasons about GLM's 5-hour/weekly PAIR; with one of them
+    // missing the min() that picks the binding window is meaningless.
+    if (fiveHour === undefined || weekly === undefined) {
+        logger.debug("budget: quota payload carried no recognizable 5-hour/weekly pair, treating as unknown");
+        return unknownSnapshot(fetchedAt);
+    }
+    return {
+        provider: "zai.zcode",
+        unit: "credit",
+        costClass: "subscription",
+        fiveHour: windowFrom(fiveHour),
+        weekly: windowFrom(weekly),
+        confidence: "exact",
+        fetchedAt,
+    };
+}
+function unknownSnapshot(fetchedAt) {
+    return {
+        provider: "zai.zcode",
+        unit: "credit",
+        costClass: "subscription",
+        fiveHour: ZERO_WINDOW,
+        weekly: ZERO_WINDOW,
+        confidence: "unknown",
+        fetchedAt,
+    };
+}
+/**
+ * The Z.ai quota as a BudgetSnapshot, read through a short-lived file cache
+ * so a burst of runs makes ONE request.
+ *
+ * FAIL-OPEN is the contract of this function: no key, endpoint down, HTTP
+ * error, malformed body, unparseable cache — every one of those returns an
+ * all-zero snapshot with confidence "unknown". This function never throws
+ * and never rejects; a monitoring outage must not block work, it degrades
+ * routing to "run normally".
+ */
+export async function fetchBudget(deps) {
+    const home = deps.home ?? os.homedir();
+    const now = deps.now ?? (() => new Date());
+    const ttlSec = deps.ttlSec ?? DEFAULT_TTL_SEC;
+    try {
+        // `refresh` (what --refresh-quota will drive) bypasses the cache without
+        // deleting it — the next normal read may still use the fresh entry this
+        // fetch writes.
+        if (!deps.refresh) {
+            const cached = readCachedSnapshot(home);
+            // NaN from an unparseable fetchedAt compares false, i.e. stale: a cache
+            // entry with no valid timestamp must never suppress a live fetch.
+            if (cached !== null && now().getTime() - Date.parse(cached.fetchedAt) < ttlSec * 1000) {
+                return { ...cached, confidence: "cached" };
+            }
+        }
+        if (deps.key === undefined || deps.key.length === 0) {
+            return unknownSnapshot(now().toISOString());
+        }
+        const data = await fetchZaiQuota(deps.key, deps.fetchImpl ?? fetch);
+        const snapshot = snapshotFrom(data, now().toISOString());
+        writeCachedSnapshot(home, snapshot);
+        return snapshot;
+    }
+    catch (error) {
+        logger.debug(`budget: quota unavailable, failing open (${errorMessage(error)})`);
+        return unknownSnapshot(now().toISOString());
+    }
+}
+/**
+ * Zone classification for routing and warnings (doc §11). The worst window
+ * wins — a healthy 5-hour window cannot paper over an exhausted weekly one.
+ *
+ * confidence "unknown" returns HEALTHY on purpose, not CRITICAL: unknown
+ * windows are all-zero, and a naive min() over them would read "no credits
+ * left" and throttle every run for the whole duration of a monitoring
+ * outage — the exact opposite of fail-open. An outage degrades to "run
+ * normally, warn once".
+ */
+export function zoneFor(snapshot, thresholds) {
+    if (snapshot.confidence === "unknown") {
+        return "HEALTHY";
+    }
+    const ratio = Math.min(snapshot.fiveHour.remainingRatio, snapshot.weekly.remainingRatio);
+    if (ratio < thresholds.criticalBelow) {
+        return "CRITICAL";
+    }
+    if (ratio < thresholds.handoffReadyBelow) {
+        return "HANDOFF_READY";
+    }
+    if (ratio < thresholds.preferFlashBelow) {
+        return "CONSERVE";
+    }
+    return "HEALTHY";
+}
+/**
+ * The cache is a deduplication layer, never a source of truth: any problem
+ * reading it (missing, unreadable, unparseable, wrong shape) reads as "no
+ * cache" so the caller falls through to a live fetch.
+ */
+function readCachedSnapshot(home) {
+    const file = quotaCachePath(home);
+    let text;
+    try {
+        text = fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        logger.debug(`budget: unparseable quota cache at ${file} ignored`);
+        return null;
+    }
+    if (!isSnapshotLike(parsed)) {
+        logger.debug(`budget: quota cache at ${file} is not a snapshot, ignored`);
+        return null;
+    }
+    return parsed;
+}
+/** Write failures are debug-logged, never thrown — a read-only home must not fail a run. */
+function writeCachedSnapshot(home, snapshot) {
+    const file = quotaCachePath(home);
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, JSON.stringify(snapshot) + "\n", "utf8");
+    }
+    catch (error) {
+        logger.debug(`budget: could not write quota cache (${errorMessage(error)})`);
+    }
+}
+/**
+ * "Parses and has the fields the consumers read": enough shape to trust the
+ * cached numbers without duplicating the snapshot definition. Anything that
+ * fails this was not written by this build.
+ */
+function isSnapshotLike(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const candidate = value;
+    return ((candidate.confidence === "exact" ||
+        candidate.confidence === "cached" ||
+        candidate.confidence === "unknown") &&
+        typeof candidate.fetchedAt === "string" &&
+        isWindowLike(candidate.fiveHour) &&
+        isWindowLike(candidate.weekly));
+}
+function isWindowLike(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const window = value;
+    return (typeof window.used === "number" &&
+        typeof window.limit === "number" &&
+        typeof window.remaining === "number" &&
+        typeof window.remainingRatio === "number" &&
+        (window.resetAt === null || typeof window.resetAt === "string"));
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/cli.js

@@ -16,6 +16,9 @@ import { uninstallCommand } from "./commands/uninstall.js";
 import { delegateCommand } from "./commands/delegate.js";
 import { benchmarkCommand } from "./commands/benchmark.js";
 import { usageCommand } from "./commands/usage.js";
+import { runsCleanCommand, runsCommand, runsLogsCommand, runsShowCommand } from "./commands/runs.js";
+import { watchCommand } from "./commands/watch.js";
+import { dashboardCommand } from "./commands/dashboard.js";
 import { mcpCommand } from "./commands/mcp.js";
 const program = new Command();
 program
@@ -109,6 +112,41 @@ program
     .command("usage")
     .description("provider usage snapshots: Z.ai Coding Plan quota + local benchmark totals")
     .action(() => execute(() => usageCommand(globalOptions())));
+const runs = program
+    .command("runs")
+    .description("inspect recorded worker runs — the default action lists them")
+    .option("--active", "list only runs in the active registry")
+    .option("--limit <n>", "show at most N runs (default 20)", (value) => Number(value))
+    .option("--json", "machine-readable JSON output")
+    .action((commandOptions) => execute(() => Promise.resolve(runsCommand({ ...globalOptions(), ...commandOptions }))));
+runs
+    .command("show <id>")
+    .description("show one run: metadata, summary numbers, per-turn tool tree")
+    .option("--json", "machine-readable JSON output")
+    .action((id, commandOptions) => execute(() => Promise.resolve(runsShowCommand(id, { ...globalOptions(), ...commandOptions }))));
+runs
+    .command("logs <id>")
+    .description("render the run's events.jsonl, one line per event")
+    .option("--json", "print the raw events.jsonl lines unchanged")
+    .action((id, commandOptions) => execute(() => Promise.resolve(runsLogsCommand(id, { ...globalOptions(), ...commandOptions }))));
+runs
+    .command("clean")
+    .description("prune history by age/count and reap orphaned active runs")
+    .option("--older-than <nd>", 'prune runs older than N days, e.g. "30d" (default: history.retentionDays)')
+    .option("--orphans", "reap active runs whose heartbeat is stale and whose pid is dead")
+    .option("--dry-run", "print what would happen without changing anything")
+    .option("--json", "machine-readable JSON output")
+    .action((commandOptions) => execute(() => Promise.resolve(runsCleanCommand({ ...globalOptions(), ...commandOptions }))));
+program
+    .command("watch [run-id]")
+    .description("attach to a running run and follow its progress live (newest active run by default)")
+    .option("--from-start", "render the events written before attaching, then follow")
+    .action((runId, commandOptions) => execute(() => watchCommand({ ...globalOptions(), runId, ...commandOptions })));
+program
+    .command("dashboard")
+    .description("quota + active runs + recent runs: one snapshot when piped, a live view on a TTY")
+    .option("--interval <seconds>", "repaint interval in seconds on a TTY (default 2)", (value) => Number(value))
+    .action((commandOptions) => execute(() => dashboardCommand({ ...globalOptions(), ...commandOptions })));
 const mcp = program
     .command("mcp")
     .description("optional glm-mcp MCP server: snippet, install, remove")

package/dist/commands/dashboard.js

@@ -0,0 +1,348 @@
+import os from "node:os";
+import path from "node:path";
+import { loadConfig } from "../core/config.js";
+import { Errors } from "../core/errors.js";
+import { logger } from "../core/logging.js";
+import { runDir } from "../core/paths.js";
+import { resolveZaiApiKey } from "../core/zai-key.js";
+import { isOrphaned, listActive, listHistory } from "../runs/registry.js";
+import { readEvents } from "../runs/store.js";
+import { ansi, createWriter, paint } from "../tui/render.js";
+import { describeWindow, fetchZaiQuota } from "../core/zai-quota.js";
+import { emitJson } from "./context.js";
+// Display-only zone thresholds for the dashboard's one-word verdict. Phase E
+// owns the real routing thresholds (routing.preferFlashBelow etc.); these must
+// stay independent so restyling the dashboard can never change a routing
+// decision, and vice versa.
+const ZONE_OK_ABOVE_RATIO = 0.3;
+const ZONE_LOW_ABOVE_RATIO = 0.15;
+/** Doc §8: recent runs are the last few, not the whole history. */
+const RECENT_LIMIT = 5;
+const DEFAULT_INTERVAL_SEC = 2;
+/**
+ * glm-router dashboard — quota + active runs + recent runs + errors in one
+ * frame (doc §8). Non-TTY (or --json) prints exactly ONE snapshot and exits 0,
+ * so the command is pipeable and a monitoring outage never looks like a broken
+ * tool; TTY repaints the whole frame every --interval seconds until Ctrl+C.
+ */
+export async function dashboardCommand(options, deps = {}) {
+    const intervalSec = options.interval ?? DEFAULT_INTERVAL_SEC;
+    if (!Number.isFinite(intervalSec) || intervalSec <= 0) {
+        throw Errors.invalidArgs(`--interval expects a positive number of seconds, got "${String(options.interval)}"`);
+    }
+    const stream = deps.stdout ?? process.stdout;
+    const isTTY = deps.isTTY ?? stream.isTTY === true;
+    if (options.json || !isTTY) {
+        const snapshot = await buildSnapshot(deps);
+        if (options.json) {
+            emitJson(snapshotJson(snapshot));
+        }
+        else {
+            const writer = createWriter(stream); // non-TTY: color off, no ANSI
+            writer.line(renderSnapshot(snapshot, writer));
+        }
+        return 0;
+    }
+    // TTY: repaint by clearing and rewriting — never scroll. All cursor control
+    // goes through render.ts's ansi helpers (D1: no escape codes here).
+    const writer = createWriter(stream);
+    writer.write(ansi.hideCursor);
+    return new Promise((resolve) => {
+        let paintedLines = 0;
+        let painting = false;
+        let stopped = false;
+        const stop = () => {
+            if (stopped) {
+                return;
+            }
+            stopped = true;
+            clearInterval(timer);
+            process.removeListener("SIGINT", onSigint);
+            writer.write(ansi.showCursor);
+            resolve(0);
+        };
+        const onSigint = () => stop();
+        const repaint = async () => {
+            if (stopped || painting) {
+                return;
+            }
+            painting = true;
+            try {
+                const frame = renderSnapshot(await buildSnapshot(deps), writer);
+                if (stopped) {
+                    return;
+                }
+                if (paintedLines > 0) {
+                    const clear = ansi.cursorUp(1) + ansi.clearLine;
+                    writer.write(clear.repeat(paintedLines));
+                }
+                writer.write(`${frame}\n`);
+                paintedLines = frame.split("\n").length;
+            }
+            catch (error) {
+                // One failed repaint (e.g. a transient quota timeout) must not kill
+                // the loop; the next tick replaces the frame.
+                logger.debug(`dashboard: repaint failed: ${errorMessage(error)}`);
+            }
+            finally {
+                painting = false;
+            }
+        };
+        const timer = setInterval(() => {
+            void repaint();
+        }, intervalSec * 1000);
+        process.on("SIGINT", onSigint);
+        void repaint();
+    });
+}
+/** Gathers one frame from the quota endpoint and the run registry. */
+async function buildSnapshot(deps) {
+    const home = deps.home ?? os.homedir();
+    const now = deps.now ?? (() => new Date());
+    const nowMs = now().getTime();
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const resolveKey = deps.resolveKey ?? (() => resolveZaiApiKey());
+    // Fail-open by contract: a monitoring outage must never fail the dashboard
+    // (or block work) — it renders as one unavailable line, exit stays 0.
+    let quota;
+    const resolved = resolveKey();
+    if (resolved === undefined) {
+        quota = { ok: false, level: null, zone: "unknown", windows: [], error: "no Z.ai API key configured" };
+    }
+    else {
+        try {
+            const data = await fetchZaiQuota(resolved.key, fetchImpl);
+            const windows = (data.limits ?? []).map(windowView);
+            quota = {
+                ok: true,
+                level: data.level ?? null,
+                zone: zoneFor(windows.map((window) => window.remainingRatio)),
+                windows,
+                error: null,
+            };
+        }
+        catch (error) {
+            quota = {
+                ok: false,
+                level: null,
+                zone: "unknown",
+                windows: [],
+                error: errorMessage(error),
+            };
+        }
+    }
+    const active = listActive(home).map((run) => ({
+        id: run.id,
+        state: run.state,
+        kind: run.kind,
+        model: run.model,
+        elapsedMs: elapsedSince(run.startedAt, nowMs),
+        cwd: run.cwd,
+        orphaned: isOrphaned(run, { now: () => nowMs, isAlive: deps.isAlive }),
+    }));
+    // `listHistory` also returns active runs (their directory exists from the
+    // first event, with no summary yet — which reads as CRASHED). Recent Runs is
+    // "how runs ended": the live ones are the section above, and showing them
+    // here as crashed would be actively misleading.
+    const activeIds = new Set(active.map((row) => row.id));
+    const recent = listHistory(home)
+        .filter((ref) => !activeIds.has(ref.id))
+        .slice(0, RECENT_LIMIT)
+        .map((ref) => ({
+        id: ref.id,
+        state: ref.state,
+        durationMs: ref.summary?.durationMs ?? null,
+        turns: ref.summary?.turns ?? null,
+        files: ref.summary?.filesChanged.length ?? null,
+        reason: failedReason(home, ref),
+    }));
+    return { generatedAt: new Date(nowMs).toISOString(), quota, active, recent, model: loadConfig(home).models.main };
+}
+/** The machine shape — mirrors the text frame key for key. */
+function snapshotJson(snapshot) {
+    return {
+        generatedAt: snapshot.generatedAt,
+        model: snapshot.model,
+        quota: snapshot.quota,
+        active: snapshot.active,
+        recent: snapshot.recent,
+        errors: snapshot.recent
+            .filter((row) => row.state === "FAILED" || row.state === "CRASHED")
+            .map((row) => ({ id: row.id, state: row.state, reason: row.reason })),
+    };
+}
+function renderSnapshot(snapshot, writer) {
+    const lines = [`GLM Coding Router — dashboard ${formatLocalTime(snapshot.generatedAt)}`, ""];
+    if (snapshot.quota.ok) {
+        const level = snapshot.quota.level !== null ? ` (level: ${snapshot.quota.level})` : "";
+        lines.push(`Quota${level} — ${paintZone(writer, snapshot.quota.zone)}`);
+        if (snapshot.quota.windows.length === 0) {
+            lines.push("  (no quota windows reported)");
+        }
+        for (const window of snapshot.quota.windows) {
+            const used = window.used !== null ? String(window.used) : "?";
+            const total = window.limit !== null ? String(window.limit) : "?";
+            const percent = window.percent !== null ? ` (${String(window.percent)}%)` : "";
+            const resets = window.resetsAt !== null ? ` · resets ${window.resetsAt}` : "";
+            lines.push(`  ${window.window.padEnd(15)} ${used} / ${total} credits${percent} · ` +
+                `${paintZone(writer, zoneFor([window.remainingRatio]))}${resets}`);
+        }
+    }
+    else {
+        lines.push("Quota", `  quota unavailable — ${snapshot.quota.error ?? "unknown error"}`);
+    }
+    lines.push("", "Active Runs");
+    if (snapshot.active.length === 0) {
+        lines.push("  (none)");
+    }
+    else {
+        const rows = snapshot.active.map((row) => [
+            row.id.slice(-6),
+            row.state,
+            row.kind,
+            row.model,
+            row.elapsedMs !== null ? formatDuration(row.elapsedMs) : "—",
+            (path.basename(row.cwd) || row.cwd) + (row.orphaned ? paint(writer, "yellow", " (orphaned)") : ""),
+        ]);
+        for (const line of renderRows(rows)) {
+            lines.push(`  ${line}`);
+        }
+    }
+    lines.push("", "Recent Runs");
+    if (snapshot.recent.length === 0) {
+        lines.push("  (none)");
+    }
+    else {
+        for (const row of snapshot.recent) {
+            const numbers = row.durationMs === null && row.turns === null && row.files === null
+                ? "—"
+                : [
+                    row.durationMs !== null ? formatDuration(row.durationMs) : null,
+                    row.turns !== null ? `${String(row.turns)} ${row.turns === 1 ? "turn" : "turns"}` : null,
+                    row.files !== null ? `${String(row.files)} ${row.files === 1 ? "file" : "files"}` : null,
+                ]
+                    .filter((part) => part !== null)
+                    .join(" · ");
+            lines.push(`  ${row.id.slice(-6)}  ${row.state.padEnd(10)} ${numbers}`);
+        }
+    }
+    const failed = snapshot.recent.filter((row) => row.state === "FAILED" || row.state === "CRASHED");
+    lines.push("", "Errors");
+    if (failed.length === 0) {
+        lines.push("  (none)");
+    }
+    else {
+        for (const row of failed) {
+            const reason = row.reason !== null ? ` — ${row.reason}` : "";
+            lines.push(`  ${paint(writer, "red", `✗ ${row.id.slice(-6)} ${row.state}${reason}`)}`);
+        }
+    }
+    lines.push("", `Model  ${snapshot.model}`);
+    return lines.join("\n");
+}
+function paintZone(writer, zone) {
+    const style = zone === "ok" ? "green" : zone === "low" ? "yellow" : zone === "critical" ? "red" : null;
+    return style !== null ? paint(writer, style, zone) : zone;
+}
+/**
+ * Worst window wins, matching how the router will judge the budget: a healthy
+ * 5-hour window cannot paper over an exhausted weekly one.
+ */
+function zoneFor(ratios) {
+    const known = ratios.filter((ratio) => typeof ratio === "number" && Number.isFinite(ratio));
+    if (known.length === 0) {
+        return "unknown";
+    }
+    const worst = Math.min(...known);
+    if (worst > ZONE_OK_ABOVE_RATIO) {
+        return "ok";
+    }
+    if (worst > ZONE_LOW_ABOVE_RATIO) {
+        return "low";
+    }
+    return "critical";
+}
+function windowView(limit) {
+    const used = typeof limit.currentValue === "number" ? limit.currentValue : null;
+    const total = typeof limit.usage === "number" ? limit.usage : null;
+    const percent = typeof limit.percentage === "number"
+        ? limit.percentage
+        : used !== null && total !== null && total > 0
+            ? Math.round((used / total) * 100)
+            : null;
+    const remainingRatio = typeof limit.remaining === "number" && total !== null && total > 0
+        ? limit.remaining / total
+        : percent !== null
+            ? (100 - percent) / 100
+            : null;
+    const resetsAt = typeof limit.nextResetTime === "number" && Number.isFinite(limit.nextResetTime)
+        ? new Date(limit.nextResetTime).toISOString()
+        : null;
+    return { window: describeWindow(limit), used, limit: total, percent, remainingRatio, resetsAt };
+}
+/**
+ * Why a run failed. `RunSummary` carries no reason field today (Phase B's
+ * choice), so the line falls back to the run's own `RunFailed` event — read
+ * only for FAILED/CRASHED entries, at most RECENT_LIMIT of them.
+ */
+function failedReason(home, ref) {
+    if (ref.state !== "FAILED" && ref.state !== "CRASHED") {
+        return null;
+    }
+    const fromSummary = ref.summary !== null ? ref.summary.reason : undefined;
+    if (typeof fromSummary === "string" && fromSummary.length > 0) {
+        return fromSummary;
+    }
+    const events = readEvents(runDir(home, ref.date, ref.id));
+    for (let index = events.length - 1; index >= 0; index--) {
+        const event = events[index];
+        if (event.type === "RunFailed") {
+            return event.reason;
+        }
+    }
+    return null;
+}
+/** Pads each column to the widest cell — a model or cwd of any length must not break the frame. */
+function renderRows(rows) {
+    const widths = [];
+    for (const row of rows) {
+        row.forEach((cell, column) => {
+            widths[column] = Math.max(widths[column] ?? 0, cell.length);
+        });
+    }
+    return rows.map((row) => row.map((cell, column) => cell.padEnd(widths[column] ?? 0)).join("  ").trimEnd());
+}
+/** Milliseconds since an ISO timestamp; null when unparseable. */
+function elapsedSince(iso, nowMs) {
+    const startedMs = Date.parse(iso);
+    return Number.isFinite(startedMs) ? Math.max(0, nowMs - startedMs) : null;
+}
+/** Local time built from the date's own components so no locale can change it. */
+function formatLocalTime(iso) {
+    const date = new Date(iso);
+    if (Number.isNaN(date.getTime())) {
+        return iso;
+    }
+    const p2 = (value) => String(value).padStart(2, "0");
+    return (`${date.getFullYear()}-${p2(date.getMonth() + 1)}-${p2(date.getDate())} ` +
+        `${p2(date.getHours())}:${p2(date.getMinutes())}:${p2(date.getSeconds())}`);
+}
+/** "5.4s", "2m 13s", "1h 04m" — one decimal below a minute, where it is honest. */
+function formatDuration(durationMs) {
+    if (!Number.isFinite(durationMs) || durationMs < 0) {
+        return "—";
+    }
+    const seconds = durationMs / 1000;
+    if (seconds < 60) {
+        return `${seconds.toFixed(1)}s`;
+    }
+    const totalSeconds = Math.floor(seconds);
+    const minutes = Math.floor(totalSeconds / 60);
+    if (minutes < 60) {
+        return `${minutes}m ${String(totalSeconds % 60).padStart(2, "0")}s`;
+    }
+    return `${Math.floor(minutes / 60)}h ${String(minutes % 60).padStart(2, "0")}m`;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}