vramtop.cpp

// vramtop — a Task Manager for the GPU: who holds the VRAM, who burns the engines.
// Human views (snapshot / --watch / --gui treemap) + agent surfaces (--json, NDJSON,
// --mcp stdio server, --stamp, --spool fusor lane). C/C++ only, OS APIs only, single exe.
//
// Build: build.bat (MSVC, /std:c++20 /W4 /permissive- /utf-8 /MT) -> vramtop.exe + vramtopw.exe
#include "app_util.h"
#include "treemap.h"

#ifndef WIN32_LEAN_AND_MEAN
#define WIN32_LEAN_AND_MEAN
#endif
#ifndef NOMINMAX
#define NOMINMAX
#endif
#include <windows.h>

#include <atomic>
#include <cctype>
#include <cmath>
#include <cstdlib>
#include <cstring>
#include <ctime>
#include <iostream>

namespace vramtop {

int run_gui(const Opts& o);  // vramtop_gui.cpp

// ======================================================================
// JSON emit
// ======================================================================
static std::string jesc(const std::string& s) {
    std::string o;
    o.reserve(s.size() + 8);
    for (unsigned char c : s) {
        switch (c) {
            case '"': o += "\\\""; break;
            case '\\': o += "\\\\"; break;
            case '\n': o += "\\n"; break;
            case '\r': o += "\\r"; break;
            case '\t': o += "\\t"; break;
            default:
                if (c < 0x20) o += ssprintf("\\u%04x", c);
                else o += (char)c;
        }
    }
    return o;
}
static std::string jstr(const std::string& s) { return "\"" + jesc(s) + "\""; }
static std::string jnum_or_null(bool ok, const char* fmt, double v) {
    return ok ? ssprintf(fmt, v) : std::string("null");
}

std::string to_json(const Snapshot& s, double min_mb, int top) {
    std::string j;
    j.reserve(4096);
    j += "{\"tool\":\"vramtop\",\"version\":" + jstr(kVersion);
    j += ssprintf(",\"wall_ms\":%llu,\"sample_ms\":%u,", (unsigned long long)s.wall_ms, s.sample_ms);
    j += "\"error\":" + (s.error.empty() ? std::string("null") : jstr(s.error));
    j += ",\"adapters\":[";
    for (size_t i = 0; i < s.adapters.size(); ++i) {
        const auto& a = s.adapters[i];
        if (i) j += ",";
        j += ssprintf("{\"index\":%zu,", i);
        j += "\"name\":" + jstr(a.name) + ",\"vendor\":" + jstr(vendor_name(a.vendor_id));
        j += ssprintf(",\"luid\":\"0x%08X_0x%08X\",\"phys\":%u,\"software\":%s,",
                      a.luid_hi, a.luid_lo, a.phys, a.software ? "true" : "false");
        j += ssprintf("\"vram_total_bytes\":%llu,\"vram_used_bytes\":%llu,\"vram_budget_bytes\":%llu,",
                      (unsigned long long)a.vram_total, (unsigned long long)a.vram_used,
                      (unsigned long long)a.vram_budget);
        j += ssprintf("\"shared_total_bytes\":%llu,\"shared_used_bytes\":%llu,\"sysmem_used_bytes\":%llu,",
                      (unsigned long long)a.shared_total, (unsigned long long)a.shared_used,
                      (unsigned long long)a.sysmem_used);
        j += ssprintf("\"util_pct\":%.1f,\"engines\":[", a.util_pct);
        for (size_t e = 0; e < a.engines.size(); ++e) {
            if (e) j += ",";
            j += "{\"name\":" + jstr(a.engines[e].name) + ssprintf(",\"pct\":%.1f}", a.engines[e].pct);
        }
        j += "],";
        j += "\"temp_c\":" + jnum_or_null(a.temp_c >= 0, "%.1f", a.temp_c);
        j += ",\"fan_rpm\":" + jnum_or_null(a.fan_rpm >= 0, "%.0f", (double)a.fan_rpm);
        j += ",\"power_pct\":" + jnum_or_null(a.power_pct >= 0, "%.1f", a.power_pct);
        j += ",\"mem_clock_mhz\":" + jnum_or_null(a.mem_clock_mhz >= 0, "%.0f", a.mem_clock_mhz);
        j += ",\"mem_clock_max_mhz\":" + jnum_or_null(a.mem_clock_max_mhz >= 0, "%.0f", a.mem_clock_max_mhz) + "}";
    }
    j += "],\"processes\":[";
    const uint64_t min_b = (uint64_t)(min_mb * 1048576.0);
    int emitted = 0;
    for (const auto& p : s.procs) {
        if (p.weight() < min_b && p.sysmem < min_b && p.shared < min_b && p.util_pct < 0.5) continue;
        if (top > 0 && emitted >= top) break;
        if (emitted) j += ",";
        emitted++;
        j += ssprintf("{\"pid\":%u,\"adapter\":%d,", p.pid, p.adapter);
        j += "\"name\":" + jstr(p.name) + ",\"path\":" + jstr(p.path) + ",";
        j += (p.resident != kUnknown64
                  ? ssprintf("\"vram_resident_bytes\":%llu,", (unsigned long long)p.resident)
                  : std::string("\"vram_resident_bytes\":null,"));
        j += ssprintf("\"vram_committed_bytes\":%llu,\"vram_bytes\":%llu,\"sysmem_bytes\":%llu,\"shared_bytes\":%llu,",
                      (unsigned long long)p.committed, (unsigned long long)p.weight(),
                      (unsigned long long)p.sysmem, (unsigned long long)p.shared);
        j += ssprintf("\"util_pct\":%.1f,", p.util_pct);
        j += "\"top_engine\":" + jstr(p.top_engine) + "}";
    }
    j += "]}";
    return j;
}

// ======================================================================
// Mini JSON parse (MCP requests + selftest roundtrip). Tolerant, bounded.
// ======================================================================
struct JV {
    enum T { Null, Bool, Num, Str, Arr, Obj } t = Null;
    bool b = false;
    double num = 0;
    std::string raw;  // numbers: original token (round-trips ids)
    std::string s;
    std::vector<JV> arr;
    std::vector<std::pair<std::string, JV>> obj;
    const JV* get(const char* k) const {
        for (const auto& kv : obj)
            if (kv.first == k) return &kv.second;
        return nullptr;
    }
    double as_num(double d) const { return t == Num ? num : d; }
    bool as_bool(bool d) const { return t == Bool ? b : d; }
    std::string as_str(const char* d) const { return t == Str ? s : d; }
};

static void jskip(const std::string& in, size_t& i) {
    while (i < in.size() && (in[i] == ' ' || in[i] == '\t' || in[i] == '\r' || in[i] == '\n')) ++i;
}
static bool jval(const std::string& in, size_t& i, JV& out, int depth);

static bool jstring(const std::string& in, size_t& i, std::string& out) {
    if (i >= in.size() || in[i] != '"') return false;
    ++i;
    out.clear();
    while (i < in.size()) {
        char c = in[i++];
        if (c == '"') return true;
        if (c != '\\') { out += c; continue; }
        if (i >= in.size()) return false;
        char e = in[i++];
        switch (e) {
            case '"': out += '"'; break;
            case '\\': out += '\\'; break;
            case '/': out += '/'; break;
            case 'n': out += '\n'; break;
            case 't': out += '\t'; break;
            case 'r': out += '\r'; break;
            case 'b': out += '\b'; break;
            case 'f': out += '\f'; break;
            case 'u': {
                if (i + 4 > in.size()) return false;
                unsigned cp = (unsigned)strtoul(in.substr(i, 4).c_str(), nullptr, 16);
                i += 4;
                if (cp >= 0xD800 && cp <= 0xDBFF && i + 6 <= in.size() && in[i] == '\\' && in[i + 1] == 'u') {
                    unsigned lo = (unsigned)strtoul(in.substr(i + 2, 4).c_str(), nullptr, 16);
                    if (lo >= 0xDC00 && lo <= 0xDFFF) {
                        cp = 0x10000 + ((cp - 0xD800) << 10) + (lo - 0xDC00);
                        i += 6;
                    }
                }
                if (cp < 0x80) out += (char)cp;
                else if (cp < 0x800) {
                    out += (char)(0xC0 | (cp >> 6));
                    out += (char)(0x80 | (cp & 0x3F));
                } else if (cp < 0x10000) {
                    out += (char)(0xE0 | (cp >> 12));
                    out += (char)(0x80 | ((cp >> 6) & 0x3F));
                    out += (char)(0x80 | (cp & 0x3F));
                } else {
                    out += (char)(0xF0 | (cp >> 18));
                    out += (char)(0x80 | ((cp >> 12) & 0x3F));
                    out += (char)(0x80 | ((cp >> 6) & 0x3F));
                    out += (char)(0x80 | (cp & 0x3F));
                }
                break;
            }
            default: return false;
        }
    }
    return false;
}

static bool jval(const std::string& in, size_t& i, JV& out, int depth) {
    if (depth > 48) return false;
    jskip(in, i);
    if (i >= in.size()) return false;
    const char c = in[i];
    if (c == '{') {
        out.t = JV::Obj;
        ++i;
        jskip(in, i);
        if (i < in.size() && in[i] == '}') { ++i; return true; }
        while (i < in.size()) {
            jskip(in, i);
            std::string key;
            if (!jstring(in, i, key)) return false;
            jskip(in, i);
            if (i >= in.size() || in[i] != ':') return false;
            ++i;
            JV v;
            if (!jval(in, i, v, depth + 1)) return false;
            out.obj.emplace_back(std::move(key), std::move(v));
            jskip(in, i);
            if (i < in.size() && in[i] == ',') { ++i; continue; }
            if (i < in.size() && in[i] == '}') { ++i; return true; }
            return false;
        }
        return false;
    }
    if (c == '[') {
        out.t = JV::Arr;
        ++i;
        jskip(in, i);
        if (i < in.size() && in[i] == ']') { ++i; return true; }
        while (i < in.size()) {
            JV v;
            if (!jval(in, i, v, depth + 1)) return false;
            out.arr.push_back(std::move(v));
            jskip(in, i);
            if (i < in.size() && in[i] == ',') { ++i; continue; }
            if (i < in.size() && in[i] == ']') { ++i; return true; }
            return false;
        }
        return false;
    }
    if (c == '"') { out.t = JV::Str; return jstring(in, i, out.s); }
    if (!strncmp(in.c_str() + i, "true", 4)) { out.t = JV::Bool; out.b = true; i += 4; return true; }
    if (!strncmp(in.c_str() + i, "false", 5)) { out.t = JV::Bool; out.b = false; i += 5; return true; }
    if (!strncmp(in.c_str() + i, "null", 4)) { out.t = JV::Null; i += 4; return true; }
    const size_t start = i;
    if (in[i] == '-') ++i;
    while (i < in.size() && (isdigit((unsigned char)in[i]) || in[i] == '.' || in[i] == 'e' ||
                             in[i] == 'E' || in[i] == '+' || in[i] == '-'))
        ++i;
    if (i == start) return false;
    out.t = JV::Num;
    out.raw = in.substr(start, i - start);
    out.num = strtod(out.raw.c_str(), nullptr);
    return true;
}

static bool jparse(const std::string& in, JV& out) {
    size_t i = 0;
    if (!jval(in, i, out, 0)) return false;
    jskip(in, i);
    return i == in.size();
}

// ======================================================================
// ANSI console rendering
// ======================================================================
namespace clr {
constexpr const char* reset = "\x1b[0m";
constexpr const char* bold = "\x1b[1m";
constexpr const char* dim = "\x1b[38;5;244m";
constexpr const char* track = "\x1b[38;5;238m";
constexpr const char* grn = "\x1b[38;2;62;207;108m";
constexpr const char* amb = "\x1b[38;2;245;185;66m";
constexpr const char* red = "\x1b[38;2;240;90;90m";
constexpr const char* err = "\x1b[1;38;2;255;96;96m";
}  // namespace clr

static const char* pct_color(double pct) {
    return pct < 60 ? clr::grn : (pct < 85 ? clr::amb : clr::red);
}

static std::string bar(double frac, int width, const char* color, bool ansi) {
    frac = std::clamp(frac, 0.0, 1.0);
    std::string b;
    if (!ansi) {
        const int f = (int)(frac * width + 0.5);
        b.append((size_t)f, '#');
        b.append((size_t)(width - f), '.');
        return b;
    }
    static const char* eighth[] = { "\u258F", "\u258E", "\u258D", "\u258C", "\u258B", "\u258A", "\u2589" };
    const int fill8 = (int)(frac * width * 8 + 0.5);
    const int full = fill8 / 8, rem = fill8 % 8;
    b += color;
    for (int k = 0; k < full; ++k) b += "\u2588";
    int used = full;
    if (rem && full < width) { b += eighth[rem - 1]; used++; }
    b += clr::track;
    for (int k = used; k < width; ++k) b += "\u2591";
    b += clr::reset;
    return b;
}

struct RenderCtx {
    bool ansi = true;
    int width = 100;
    bool watch = false;
    bool paused = false;
};

static std::string render(const Snapshot& s, const Opts& o, const RenderCtx& rc) {
    std::string out;
    out.reserve(8192);
    const bool ansi = rc.ansi;
    const char* D = ansi ? clr::dim : "";
    const char* R = ansi ? clr::reset : "";
    char tbuf[64];
    time_t tt = (time_t)(s.wall_ms / 1000);
    struct tm tmv;
    localtime_s(&tmv, &tt);
    strftime(tbuf, sizeof(tbuf), "%Y-%m-%d %H:%M:%S", &tmv);
    out += ansi ? clr::bold : "";
    out += "vramtop " + std::string(kVersion);
    out += R;
    out += ssprintf(" \u00b7 %s", tbuf);
    if (s.sample_ms > 0) out += ssprintf(" \u00b7 window %u ms", s.sample_ms);
    if (rc.watch) {
        out += D;
        out += ssprintf("   [q]uit [s]ort:%s [g]roup%s [p]%s", sort_name(o.sort), o.group ? "\u2713" : "",
                        rc.paused ? " RESUME \u2014 PAUSED" : "ause");
        out += R;
    }
    out += "\n";
    if (!s.error.empty()) {
        out += ansi ? clr::err : "";
        out += "! " + s.error;
        out += R;
        out += "\n";
    }

    bool any_star = false;
    for (size_t ai = 0; ai < s.adapters.size(); ++ai) {
        const auto& a = s.adapters[ai];
        if (a.software) continue;
        if (o.adapter >= 0 && (int)ai != o.adapter) continue;
        DispResult dr = display_rows(s, o, (int)ai);
        if (trivial_adapter(a, !dr.rows.empty())) {
            if (a.vram_total == 0 && a.vram_used == 0) continue;   // phantom with nothing to say
            out += "\n" + std::string(ansi ? clr::bold : "") + a.name + R + D +
                   ssprintf("   idle \u00b7 %s / %s\n", human_bytes(a.vram_used).c_str(),
                            human_bytes(a.vram_total).c_str()) + R;
            continue;
        }
        out += "\n";
        out += ansi ? clr::bold : "";
        out += a.name;
        out += R;
        std::string extras;
        if (a.temp_c >= 0) extras += ssprintf("%.0f\u00b0C", a.temp_c);
        if (a.fan_rpm > 0) extras += (extras.empty() ? "" : " \u00b7 ") + ssprintf("fan %d", a.fan_rpm);
        if (a.power_pct >= 0) extras += (extras.empty() ? "" : " \u00b7 ") + ssprintf("pwr %.0f%%", a.power_pct);
        if (a.mem_clock_mhz > 0) extras += (extras.empty() ? "" : " \u00b7 ") + ssprintf("mem %.0f MHz", a.mem_clock_mhz);
        if (!extras.empty()) out += std::string(D) + "   " + extras + R;
        out += "\n";

        const double vfrac = a.vram_total ? (double)a.vram_used / (double)a.vram_total : 0.0;
        out += " VRAM " + bar(vfrac, 26, pct_color(vfrac * 100), ansi);
        out += ssprintf(" %s / %s", human_bytes(a.vram_used).c_str(), human_bytes(a.vram_total).c_str());
        if (a.vram_total) out += ssprintf(" \u00b7 %.0f%%", vfrac * 100);
        if (a.sysmem_used >= (64ull << 20))
            out += std::string(ansi ? clr::amb : "") + ssprintf("   spill %s in RAM", human_bytes(a.sysmem_used).c_str()) + R;
        else if (a.shared_used >= (32ull << 20))
            out += ssprintf("   shared %s", human_bytes(a.shared_used).c_str());
        out += "\n";
        if (s.sample_ms > 0) {
            out += " load " + bar(a.util_pct / 100.0, 26, pct_color(a.util_pct), ansi);
            out += ssprintf(" %.0f%%", a.util_pct);
            std::string engs;
            int shown = 0;
            for (const auto& e : a.engines) {
                if (shown >= 4 || (e.pct < 0.05 && shown > 0)) break;
                engs += (shown ? " \u00b7 " : "") + short_engine(e.name) + ssprintf(" %.0f", e.pct);
                shown++;
            }
            if (!engs.empty()) out += std::string(D) + "  " + engs + R;
            out += "\n";
        }

        if (dr.rows.empty()) {
            out += std::string(D) + "  (no process rows above threshold)\n" + R;
            continue;
        }
        const int name_w = std::clamp(rc.width - 54, 18, 30);
        out += D;
        out += ssprintf("   PID  %-*s %-12s %10s %9s  %4s  %s\n", name_w, "process", "", "vram", "sysmem", "gpu%", "eng");
        out += R;
        for (const auto& r : dr.rows) {
            std::string nm = r.count > 1 ? r.name + ssprintf(" \u00d7%d", r.count) : r.name;
            nm = pad_display(trunc_display(nm, name_w), name_w);
            const double frac = a.vram_total ? (double)r.weight / (double)a.vram_total : 0.0;
            std::string vs = human_bytes(r.weight);
            if (!r.resident_known) { vs += "*"; any_star = true; }
            const std::string us = r.util < 0.5 ? "-" : ssprintf("%.0f%%", r.util);
            const std::string sm = r.sysmem >= (1ull << 20) ? human_bytes(r.sysmem) : "-";
            out += ssprintf("%6u  ", r.pid) + nm + " " + bar(frac, 12, pct_color(vfrac * 100), ansi);
            out += ssprintf(" %10s %9s  %4s  %s\n", vs.c_str(), sm.c_str(), us.c_str(), short_engine(r.eng).c_str());
        }
        if (dr.hidden > 0)
            out += std::string(D) + ssprintf("  (+%d more below %.0f MB \u2014 --min-mb 0 shows all)\n", dr.hidden, o.min_mb) + R;
    }
    if (any_star)
        out += std::string(D) + "\n * committed bytes (resident counter absent for that row \u2014 WDDM commit can exceed physical)\n" + R;
    return out;
}

// ======================================================================
// console plumbing
// ======================================================================
static bool g_vt_enabled = false;
static std::atomic<bool> g_stop{ false };
static std::atomic<int> g_ctrlc_mode{ 0 };  // 1 = watch (restore alt screen on break)

static BOOL WINAPI ctrl_handler(DWORD type) {
    if (type == CTRL_C_EVENT || type == CTRL_BREAK_EVENT || type == CTRL_CLOSE_EVENT) {
        g_stop = true;
        if (g_ctrlc_mode == 1) {
            DWORD w;
            WriteConsoleA(GetStdHandle(STD_OUTPUT_HANDLE), "\x1b[?25h\x1b[?1049l", 14, &w, nullptr);
            ExitProcess(0);
        }
        if (type != CTRL_C_EVENT) ExitProcess(0);
        return TRUE;
    }
    return FALSE;
}

static bool stdout_is_console() {
    DWORD m;
    return GetConsoleMode(GetStdHandle(STD_OUTPUT_HANDLE), &m) != 0;
}

// vramtopw.exe (windows subsystem) has no console of its own; for text modes borrow
// the parent's so `vramtopw --json` in a terminal still prints.
static void ensure_console_for_text() {
    HANDLE h = GetStdHandle(STD_OUTPUT_HANDLE);
    if (h && h != INVALID_HANDLE_VALUE) return;
    if (!AttachConsole(ATTACH_PARENT_PROCESS)) return;
    FILE* f = nullptr;
    freopen_s(&f, "CONOUT$", "w", stdout);
    freopen_s(&f, "CONOUT$", "w", stderr);
    freopen_s(&f, "CONIN$", "r", stdin);
}

static void console_setup(Opts& o) {
    if (!stdout_is_console()) { o.plain = true; return; }
    SetConsoleOutputCP(CP_UTF8);
    HANDLE h = GetStdHandle(STD_OUTPUT_HANDLE);
    DWORD m = 0;
    if (GetConsoleMode(h, &m) && SetConsoleMode(h, m | ENABLE_VIRTUAL_TERMINAL_PROCESSING))
        g_vt_enabled = true;
    else
        o.plain = true;
}

static int console_width() {
    CONSOLE_SCREEN_BUFFER_INFO bi{};
    if (GetConsoleScreenBufferInfo(GetStdHandle(STD_OUTPUT_HANDLE), &bi)) {
        const int w = bi.srWindow.Right - bi.srWindow.Left + 1;
        return std::clamp(w, 72, 150);
    }
    return 100;
}

// drain pending console input; returns the last relevant key (0 if none)
static int poll_key() {
    HANDLE h = GetStdHandle(STD_INPUT_HANDLE);
    DWORD mode;
    if (!GetConsoleMode(h, &mode)) return 0;
    int key = 0;
    INPUT_RECORD recs[32];
    DWORD n = 0;
    while (PeekConsoleInputW(h, recs, 32, &n) && n > 0) {
        ReadConsoleInputW(h, recs, 32, &n);
        for (DWORD i = 0; i < n; ++i)
            if (recs[i].EventType == KEY_EVENT && recs[i].Event.KeyEvent.bKeyDown) {
                const WORD vk = recs[i].Event.KeyEvent.wVirtualKeyCode;
                if (vk == 'Q' || vk == VK_ESCAPE || vk == 'S' || vk == 'G' || vk == 'P') key = vk;
            }
        if (n < 32) break;
    }
    return key;
}

// Wait up to ms for a relevant key (0 = timed out). Non-console stdin just sleeps.
static int wait_key(uint32_t ms) {
    HANDLE h = GetStdHandle(STD_INPUT_HANDLE);
    DWORD mode;
    if (!GetConsoleMode(h, &mode)) { Sleep(ms); return 0; }
    const ULONGLONG deadline = GetTickCount64() + ms;
    for (;;) {
        const ULONGLONG now = GetTickCount64();
        if (now >= deadline) return 0;
        if (WaitForSingleObject(h, (DWORD)(deadline - now)) != WAIT_OBJECT_0) return 0;
        if (const int k = poll_key()) return k;   // mouse/focus records: drained, keep waiting
    }
}

static void write_frame(const std::string& frame, bool ansi) {
    if (ansi) {
        std::string outb = "\x1b[H";
        for (char c : frame) {
            if (c == '\n') outb += "\x1b[K\n";
            else outb += c;
        }
        outb += "\x1b[0J";
        fwrite(outb.data(), 1, outb.size(), stdout);
    } else {
        fwrite(frame.data(), 1, frame.size(), stdout);
        fputs("----\n", stdout);
    }
    fflush(stdout);
}

static int run_watch(Opts o) {
    console_setup(o);
    const bool ansi = !o.plain;
    g_ctrlc_mode = ansi ? 1 : 0;
    SetConsoleCtrlHandler(ctrl_handler, TRUE);
    if (ansi) fputs("\x1b[?1049h\x1b[?25l", stdout);
    Collector c(true, !o.no_procs);
    c.prime();
    int frames = 0, rc = 0;
    bool paused = false, have = false;
    Snapshot last;
    ULONGLONG due = GetTickCount64() + std::min<uint32_t>(o.interval_ms, 300);   // first frame fast
    while (!g_stop) {
        const ULONGLONG now = GetTickCount64();
        const int key = now < due ? wait_key((uint32_t)(due - now)) : 0;
        bool sampled = false;
        if (key == 0) {                                   // interval elapsed
            if (!paused || !have) {
                last = c.sample();
                have = true;
                sampled = true;
                rc = last.error.empty() ? 0 : 2;
            }
            due = GetTickCount64() + o.interval_ms;
        } else {
            switch (key) {
                case 'Q': case VK_ESCAPE: g_stop = true; continue;
                case 'S': o.sort = (Opts::Sort)(((int)o.sort + 1) % 5); break;
                case 'G': o.group = !o.group; break;
                case 'P': paused = !paused; if (!paused) due = GetTickCount64(); break;
                default: break;
            }
            if (!have) continue;
        }
        RenderCtx rcx;
        rcx.ansi = ansi;
        rcx.width = console_width();
        rcx.watch = true;
        rcx.paused = paused;
        write_frame(render(last, o, rcx), ansi);
        if (sampled && o.frames > 0 && ++frames >= o.frames) break;
    }
    if (ansi) fputs("\x1b[?25h\x1b[?1049l", stdout);
    return rc;
}

static int run_ndjson(const Opts& o) {
    SetConsoleCtrlHandler(ctrl_handler, TRUE);
    Collector c(o.sample_ms > 0, !o.no_procs);
    if (c.ok() && o.sample_ms > 0) { c.prime(); Sleep(std::min(o.sample_ms, o.interval_ms)); }
    int frames = 0, rc = 0;
    while (!g_stop) {
        Snapshot s = c.sample();
        rc = s.error.empty() ? 0 : 2;
        std::string j = to_json(s, o.min_mb, o.top);
        j += "\n";
        fwrite(j.data(), 1, j.size(), stdout);
        fflush(stdout);
        if (o.frames > 0 && ++frames >= o.frames) break;
        Sleep(o.interval_ms);
    }
    return rc;
}

// ======================================================================
// --stamp: the one-line co-tenancy receipt a timing row embeds verbatim —
// "mib_free_at_load" + who else is on the card + what has spilled to RAM.
// ======================================================================
static Opts stamp_opts(const Opts& o) {
    Opts go = o;
    go.group = true;                       // tenants aggregate by name
    go.min_mb = std::max(o.min_mb, 64.0);
    go.top = 0;
    return go;
}

static std::string stamp_line(const Snapshot& s, const Opts& o, bool with_util) {
    const Opts go = stamp_opts(o);
    char tbuf[40];
    time_t tt = (time_t)(s.wall_ms / 1000);
    struct tm tmv;
    localtime_s(&tmv, &tt);
    strftime(tbuf, sizeof(tbuf), "%Y-%m-%dT%H:%M:%S", &tmv);
    std::string line = ssprintf("gpu_stamp t=%s", tbuf);
    if (!s.error.empty()) line += " error=\"" + s.error + "\"";
    for (size_t ai = 0; ai < s.adapters.size(); ++ai) {
        const auto& a = s.adapters[ai];
        DispResult dr = display_rows(s, go, (int)ai);
        if (a.vram_total == 0 || trivial_adapter(a, !dr.rows.empty())) continue;
        std::string an = short_adapter(a.name);
        for (auto& ch : an) if (ch == ' ') ch = '_';
        const uint64_t free_b = a.vram_total > a.vram_used ? a.vram_total - a.vram_used : 0;
        line += ssprintf(" %s free_mib=%llu/%llu budget_mib=%llu spill_mib=%llu", an.c_str(),
                         (unsigned long long)(free_b >> 20), (unsigned long long)(a.vram_total >> 20),
                         (unsigned long long)(a.vram_budget >> 20), (unsigned long long)(a.sysmem_used >> 20));
        if (with_util) line += ssprintf(" util=%.0f%%", a.util_pct);
        line += " tenants=";
        int shown = 0;
        for (const auto& r : dr.rows) {
            if (shown >= 8) { line += ssprintf(",+%d", (int)dr.rows.size() - shown + dr.hidden); break; }
            std::string nm = r.name;
            if (nm.size() > 4 && nm.compare(nm.size() - 4, 4, ".exe") == 0) nm.resize(nm.size() - 4);
            for (auto& ch : nm) if (ch == ' ' || ch == ',') ch = '_';
            line += (shown ? "," : "") + nm + ssprintf(":%llu", (unsigned long long)(r.weight >> 20));
            if (r.count > 1) line += ssprintf("x%d", r.count);
            shown++;
        }
        if (shown == 0) line += "none";
    }
    return line;
}

static std::string stamp_json(const Snapshot& s, const Opts& o, bool with_util) {
    const Opts go = stamp_opts(o);
    std::string j = "{\"stamp\":\"gpu\"";
    j += ssprintf(",\"wall_ms\":%llu,", (unsigned long long)s.wall_ms);
    j += "\"error\":" + (s.error.empty() ? std::string("null") : jstr(s.error));
    j += ",\"adapters\":[";
    bool first = true;
    for (size_t ai = 0; ai < s.adapters.size(); ++ai) {
        const auto& a = s.adapters[ai];
        DispResult dr = display_rows(s, go, (int)ai);
        if (a.vram_total == 0 || trivial_adapter(a, !dr.rows.empty())) continue;
        if (!first) j += ",";
        first = false;
        const uint64_t free_b = a.vram_total > a.vram_used ? a.vram_total - a.vram_used : 0;
        j += "{\"name\":" + jstr(a.name);
        j += ssprintf(",\"mib_total\":%llu,\"mib_used\":%llu,\"mib_free\":%llu,\"mib_budget\":%llu,\"mib_spill\":%llu",
                      (unsigned long long)(a.vram_total >> 20), (unsigned long long)(a.vram_used >> 20),
                      (unsigned long long)(free_b >> 20), (unsigned long long)(a.vram_budget >> 20),
                      (unsigned long long)(a.sysmem_used >> 20));
        if (with_util) j += ssprintf(",\"util_pct\":%.1f", a.util_pct);
        j += ",\"tenants\":[";
        for (size_t r = 0; r < dr.rows.size(); ++r) {
            if (r) j += ",";
            j += "{\"n\":" + jstr(dr.rows[r].name) +
                 ssprintf(",\"mib\":%llu,\"spill_mib\":%llu,\"pids\":%d}",
                          (unsigned long long)(dr.rows[r].weight >> 20),
                          (unsigned long long)(dr.rows[r].sysmem >> 20), dr.rows[r].count);
        }
        j += "]}";
    }
    j += "]}";
    return j;
}

static int run_stamp(const Opts& o) {
    const uint32_t window = o.sample_ms_set ? o.sample_ms : 0;
    Snapshot s = collect(window, true);
    std::string line = o.json ? stamp_json(s, o, window > 0) : stamp_line(s, o, window > 0);
    line += "\n";
    fwrite(line.data(), 1, line.size(), stdout);
    return s.error.empty() ? 0 : 2;
}

// ======================================================================
// --spool: change-gated fusor lane ("lane\ttext" — the format a fusor/TOWER
// tailer eats). Emits only when the world moved; silence stays silent.
// ======================================================================
static std::string spool_line(const Snapshot& s, const Opts& o) {
    std::string t;
    for (size_t ai = 0; ai < s.adapters.size(); ++ai) {
        const auto& a = s.adapters[ai];
        DispResult dr = display_rows(s, o, (int)ai);
        if (trivial_adapter(a, !dr.rows.empty())) continue;
        if (!t.empty()) t += " || ";
        t += short_adapter(a.name) + ssprintf(" %.1f/%.1fG", a.vram_used / 1073741824.0, a.vram_total / 1073741824.0);
        if (s.sample_ms > 0) t += ssprintf(" %.0f%%", a.util_pct);
        if (a.sysmem_used >= (64ull << 20)) t += ssprintf(" spill %.1fG", a.sysmem_used / 1073741824.0);
        int shown = 0;
        for (const auto& r : dr.rows) {
            if (shown >= 6) { t += ssprintf(" | +%d", (int)dr.rows.size() - shown + dr.hidden); break; }
            t += " | " + r.name + (r.count > 1 ? ssprintf("\u00d7%d", r.count) : "");
            t += ssprintf(" %.1fG", r.weight / 1073741824.0);
            if (r.util >= 1.0) t += ssprintf(" %.0f%%", r.util);
            shown++;
        }
    }
    return t;
}

static bool spool_gate(const Snapshot& prev, const Snapshot& cur, const Opts& o) {
    if (prev.adapters.size() != cur.adapters.size()) return true;
    const uint64_t gb = (uint64_t)(o.gate_mb * 1048576.0);
    auto delta = [](uint64_t a, uint64_t b) { return a > b ? a - b : b - a; };
    for (size_t i = 0; i < cur.adapters.size(); ++i) {
        const auto& a = prev.adapters[i];
        const auto& b = cur.adapters[i];
        if (delta(a.vram_used, b.vram_used) >= gb) return true;
        if (delta(a.sysmem_used, b.sysmem_used) >= gb) return true;
        if (std::fabs(a.util_pct - b.util_pct) >= o.gate_pct) return true;
    }
    const uint64_t min_b = (uint64_t)(o.min_mb * 1048576.0);
    std::map<uint32_t, uint64_t> pa, pb;
    for (const auto& p : prev.procs)
        if (p.weight() >= min_b) pa[p.pid] += p.weight();
    for (const auto& p : cur.procs)
        if (p.weight() >= min_b) pb[p.pid] += p.weight();
    if (pa.size() != pb.size()) return true;
    for (const auto& [pid, w] : pb) {
        auto it = pa.find(pid);
        if (it == pa.end() || delta(it->second, w) >= gb) return true;
    }
    return false;
}

static int run_spool(const Opts& o) {
    SetConsoleCtrlHandler(ctrl_handler, TRUE);
    FILE* f = stdout;
    if (!o.spool_file.empty()) {
        f = fopen(o.spool_file.c_str(), "ab");
        if (!f) {
            fprintf(stderr, "vramtop: cannot open spool file: %s\n", o.spool_file.c_str());
            return 1;
        }
    }
    Collector c(o.sample_ms > 0, !o.no_procs);
    if (c.ok() && o.sample_ms > 0) { c.prime(); Sleep(std::min(o.sample_ms, o.interval_ms)); }
    Snapshot last;
    bool first = true;
    int frames = 0;
    while (!g_stop) {
        Snapshot s = c.sample();
        if (first || spool_gate(last, s, o)) {
            const std::string line = o.lane + "\t" + spool_line(s, o) + "\n";
            fwrite(line.data(), 1, line.size(), f);
            fflush(f);
            last = std::move(s);
            first = false;
        }
        if (o.frames > 0 && ++frames >= o.frames) break;
        Sleep(o.interval_ms);
    }
    if (f != stdout) fclose(f);
    return 0;
}

// ======================================================================
// --mcp: newline-delimited JSON-RPC 2.0 over stdio (MCP server, two tools)
// ======================================================================
static std::string jv_id(const JV& v) {
    if (v.t == JV::Str) return jstr(v.s);
    if (v.t == JV::Num) return v.raw;
    return "null";
}
static void mcp_send(const std::string& body) {
    fwrite(body.data(), 1, body.size(), stdout);
    fputc('\n', stdout);
    fflush(stdout);
}
static void mcp_result(const std::string& id, const std::string& result) {
    mcp_send("{\"jsonrpc\":\"2.0\",\"id\":" + id + ",\"result\":" + result + "}");
}
static void mcp_error(const std::string& id, int code, const std::string& msg) {
    mcp_send("{\"jsonrpc\":\"2.0\",\"id\":" + id +
             ssprintf(",\"error\":{\"code\":%d,\"message\":", code) + jstr(msg) + "}}");
}
static std::string mcp_text(const std::string& text) {
    return "{\"content\":[{\"type\":\"text\",\"text\":" + jstr(text) + "}]}";
}

static const char* kToolsList =
    "{\"tools\":[{"
    "\"name\":\"gpu_snapshot\","
    "\"description\":\"Per-process GPU snapshot on this Windows box: every adapter (VRAM "
    "used/total bytes, engine utilization %, temperature/power, bytes spilled to system RAM) "
    "and every process touching a GPU (resident VRAM bytes, sysmem spill bytes, committed "
    "bytes, busiest engine). sample_ms:0 = fastest memory-only read.\","
    "\"inputSchema\":{\"type\":\"object\",\"properties\":{"
    "\"sample_ms\":{\"type\":\"integer\",\"minimum\":0,\"maximum\":5000,\"default\":500,"
    "\"description\":\"engine-busy sampling window in ms; 0 skips utilization\"},"
    "\"include_processes\":{\"type\":\"boolean\",\"default\":true},"
    "\"min_mb\":{\"type\":\"number\",\"default\":1,\"description\":\"drop process rows lighter than this\"},"
    "\"top\":{\"type\":\"integer\",\"default\":0,\"description\":\"keep only the N heaviest rows; 0 = all\"}"
    "}}},{"
    "\"name\":\"gpu_stamp\","
    "\"description\":\"One-line co-tenancy receipt to embed in a timing/measurement row: "
    "free VRAM MiB, app budget, MiB spilled to RAM, and the tenant list with their MiB. "
    "Call it right before/after loading a model.\","
    "\"inputSchema\":{\"type\":\"object\",\"properties\":{"
    "\"sample_ms\":{\"type\":\"integer\",\"minimum\":0,\"maximum\":5000,\"default\":0,"
    "\"description\":\"add engine load sampled over this many ms (0 = memory only)\"},"
    "\"json\":{\"type\":\"boolean\",\"default\":false,\"description\":\"return a JSON object instead of the key=value line\"}"
    "}}}]}";

static int run_mcp() {
    std::string line;
    while (std::getline(std::cin, line)) {
        if (!line.empty() && line.back() == '\r') line.pop_back();
        if (line.empty()) continue;
        JV v;
        if (!jparse(line, v) || v.t != JV::Obj) {
            mcp_error("null", -32700, "parse error");
            continue;
        }
        const JV* mv = v.get("method");
        const std::string method = mv ? mv->as_str("") : "";
        const JV* idv = v.get("id");
        if (!idv || idv->t == JV::Null) continue;  // notification — no response
        const std::string id = jv_id(*idv);
        if (method == "initialize") {
            std::string proto = "2025-06-18";
            if (const JV* p = v.get("params"))
                if (const JV* pv = p->get("protocolVersion")) proto = pv->as_str(proto.c_str());
            mcp_result(id, "{\"protocolVersion\":" + jstr(proto) +
                               ",\"capabilities\":{\"tools\":{}},\"serverInfo\":{\"name\":\"vramtop\","
                               "\"version\":" + jstr(kVersion) + "}}");
        } else if (method == "ping") {
            mcp_result(id, "{}");
        } else if (method == "tools/list") {
            mcp_result(id, kToolsList);
        } else if (method == "tools/call") {
            const JV* p = v.get("params");
            const std::string tool = p && p->get("name") ? p->get("name")->as_str("") : "";
            const JV* a = p ? p->get("arguments") : nullptr;
            auto num = [&](const char* k, double d) { return a && a->get(k) ? a->get(k)->as_num(d) : d; };
            auto bol = [&](const char* k, bool d) { return a && a->get(k) ? a->get(k)->as_bool(d) : d; };
            if (tool == "gpu_snapshot") {
                const uint32_t sample = (uint32_t)std::clamp(num("sample_ms", 500), 0.0, 5000.0);
                Snapshot s = collect(sample, bol("include_processes", true));
                mcp_result(id, mcp_text(to_json(s, num("min_mb", 1.0),
                                                (int)std::clamp(num("top", 0), 0.0, 500.0))));
            } else if (tool == "gpu_stamp") {
                const uint32_t sample = (uint32_t)std::clamp(num("sample_ms", 0), 0.0, 5000.0);
                Snapshot s = collect(sample, true);
                Opts o;
                mcp_result(id, mcp_text(bol("json", false) ? stamp_json(s, o, sample > 0)
                                                           : stamp_line(s, o, sample > 0)));
            } else {
                mcp_error(id, -32602, "unknown tool: " + tool);
            }
        } else {
            mcp_error(id, -32601, "method not found: " + method);
        }
    }
    return 0;
}

// ======================================================================
// --selftest
// ======================================================================
static int run_selftest() {
    int fails = 0;
    auto check = [&](bool ok, const std::string& what) {
        printf("  %s %s\n", ok ? "PASS" : "FAIL", what.c_str());
        if (!ok) fails++;
    };
    printf("vramtop %s --selftest\n", kVersion);
    {
        InstRef r;
        bool ok = parse_gpu_instance(L"pid_25488_luid_0x00000000_0x00011A57_phys_0_eng_11_engtype_VideoDecode", r);
        check(ok && r.has_pid && r.pid == 25488 && r.luid_hi == 0 && r.luid_lo == 0x11A57 &&
                  r.phys == 0 && r.engtype == L"VideoDecode",
              "parse engine instance");
        ok = parse_gpu_instance(L"luid_0x00000000_0x0001428B_phys_0", r);
        check(ok && !r.has_pid && r.luid_lo == 0x1428B && r.engtype.empty(), "parse adapter instance");
        check(!parse_gpu_instance(L"garbage_no_luid", r), "reject garbage instance");
    }
    check(human_bytes(512ull << 10) == "512 KB", "human_bytes KB");
    check(human_bytes(300ull << 20) == "300 MB", "human_bytes MB");
    check(human_bytes((uint64_t)(9.6 * 1073741824.0)) == "9.6 GB", "human_bytes GB");
    check(display_width("chrome.exe") == 10 && display_width("\xE6\x97\xA5\xE6\x9C\xAC") == 4, "display_width ascii + CJK");
    check(trunc_display("abcdefgh", 5) == "abcd\xE2\x80\xA6" && display_width(trunc_display("abcdefgh", 5)) == 5, "trunc_display keeps width");
    check(pad_display("ab", 4) == "ab  ", "pad_display");
    {
        std::vector<TmItem> items = { { 5, 0 }, { 3, 1 }, { 2, 2 }, { 1, 3 }, { 1, 4 }, { 0, 5 } };
        auto placed = squarify(items, { 10, 20, 100, 60 });
        double area = 0;
        bool inside = true, overlap = false;
        for (const auto& p : placed) {
            area += p.r.w * p.r.h;
            if (p.r.x < 10 - 1e-6 || p.r.y < 20 - 1e-6 || p.r.x + p.r.w > 110 + 1e-6 || p.r.y + p.r.h > 80 + 1e-6) inside = false;
        }
        for (size_t i = 0; i < placed.size(); ++i)
            for (size_t k = i + 1; k < placed.size(); ++k) {
                const auto& a = placed[i].r;
                const auto& b = placed[k].r;
                const double ox = std::min(a.x + a.w, b.x + b.w) - std::max(a.x, b.x);
                const double oy = std::min(a.y + a.h, b.y + b.h) - std::max(a.y, b.y);
                if (ox > 1e-6 && oy > 1e-6) overlap = true;
            }
        check(placed.size() == 5, "treemap drops zero weights");
        check(std::fabs(area - 6000.0) < 1e-6, "treemap covers the bounds exactly");
        check(inside && !overlap, "treemap tiles inside, no overlap");
        bool prop = true;
        for (const auto& p : placed)
            if (std::fabs(p.r.w * p.r.h - 6000.0 * items[p.id].weight / 12.0) > 1e-6) prop = false;
        check(prop, "treemap areas proportional to weights");
    }
    {
        Snapshot a, b;
        a.adapters.resize(1);
        b.adapters.resize(1);
        a.adapters[0].vram_used = 1000ull << 20;
        b.adapters[0].vram_used = 1000ull << 20;
        ProcRow p;
        p.pid = 7;
        p.adapter = 0;
        p.resident = 500ull << 20;
        a.procs.push_back(p);
        b.procs.push_back(p);
        Opts o;
        check(!spool_gate(a, b, o), "spool gate quiet when nothing moved");
        b.adapters[0].vram_used += 200ull << 20;
        check(spool_gate(a, b, o), "spool gate fires on adapter delta");
        b.adapters[0].vram_used = a.adapters[0].vram_used;
        b.procs[0].pid = 8;
        check(spool_gate(a, b, o), "spool gate fires on tenant change");
    }
    {
        Collector c(true, true);
        check(c.ok(), c.ok() ? "Collector opened the counter query" : "Collector: " + c.error());
        c.prime();
        Sleep(200);
        Snapshot s = c.sample();
        check(s.error.empty(), s.error.empty() ? "sample() no error" : "sample(): " + s.error);
        check(s.sample_ms >= 150 && s.sample_ms < 5000, ssprintf("sample() measured its window (%u ms)", s.sample_ms));
        check(!s.adapters.empty(), "at least one adapter");
        bool hw = false, cap = false;
        for (const auto& a : s.adapters)
            if (!a.software) {
                hw = true;
                if (a.vram_total > (1ull << 30)) cap = true;
            }
        check(hw, "hardware adapter present");
        check(cap, "adapter capacity > 1 GB");
        check(!s.procs.empty(), "process rows present");
        bool resident_seen = false;
        for (const auto& p : s.procs)
            if (p.resident != kUnknown64) resident_seen = true;
        check(resident_seen, "resident (Local Usage) counter present");
        const std::string j = to_json(s, 0, 0);
        JV v;
        check(jparse(j, v) && v.t == JV::Obj, "to_json parses back");
        check(v.get("adapters") && v.get("adapters")->t == JV::Arr && !v.get("adapters")->arr.empty(), "json adapters[] present");
        check(v.get("processes") && v.get("processes")->t == JV::Arr, "json processes[] present");
        Opts o;
        check(stamp_line(s, o, true).find("free_mib=") != std::string::npos, "stamp line carries free_mib");
        JV sv;
        check(jparse(stamp_json(s, o, false), sv) && sv.get("adapters"), "stamp json parses");
        printf("  info: %zu adapters, %zu proc rows, %s\n", s.adapters.size(), s.procs.size(),
               s.adapters.empty() ? "-" : s.adapters[0].name.c_str());
    }
    printf(fails ? "SELFTEST: %d FAILURE(S)\n" : "SELFTEST: ALL PASS\n", fails);
    return fails ? 3 : 0;
}

// ======================================================================
// args / help / main
// ======================================================================
static const char* kHelp = R"(vramtop %s — a Task Manager for the GPU (per-process VRAM + engine load)

USAGE
  vramtop                one pretty snapshot (auto-plain when redirected)
  vramtop -w | --watch   live TUI   keys: q quit · s sort (vram→sysmem→util→pid→name) · g group · p pause
  vramtop --gui          live treemap window   keys: G group · T pin on top · F5 refresh
                         (vramtopw.exe opens the window with no console at all — pin it to the taskbar)
  vramtop -j | --json    one snapshot as a single JSON line
  vramtop -j -w          NDJSON stream, one snapshot per interval (engine %% spans the interval)
  vramtop --stamp        one-line co-tenancy receipt: free_mib · budget · spill · tenants
                         (the mib_free_at_load line a model-load timing row embeds; memory-only
                         by default, --sample-ms adds load, --json for an object)
  vramtop --mcp          MCP stdio server — tools: gpu_snapshot, gpu_stamp
  vramtop --spool        change-gated "lane<TAB>text" stream (fusor/TOWER tailer food)
  vramtop --selftest     parser, treemap, gate, and live-collection checks

OPTIONS
  --sample-ms N      engine-busy window for one-shot reads, ms (default 500; 0 = memory only)
  --no-util          same as --sample-ms 0
  -n, --interval N   watch/stream/spool cadence, ms (default 1000)
  --frames N         stop watch/stream/spool after N frames (0 = run until quit)
  --top N            show only the N heaviest processes
  --min-mb X         hide rows lighter than X MB (default 1; 0 shows everything)
  -g, --group        aggregate rows by process name (chrome.exe x77 ...)
  --sort K           vram | sysmem | util | pid | name   (default vram)
  --adapter N        only adapter index N (see --json for indices)
  --plain            no colors / ASCII bars
  --spool-file P     append spool lines to P instead of stdout
  --lane S           spool lane tag (default "gpu")
  --gate-mb X        spool: emit when any adapter/process moves >= X MB (default 128)
  --gate-pct X       spool: emit when adapter load moves >= X points (default 15)
  -h, --help         this text          -v, --version   version

NUMBERS, HONESTLY
  vram   = bytes of that process RESIDENT in VRAM right now (kernel "Local Usage" counter —
           no process handle needed, protected processes report too).
  sysmem = that process's GPU data currently living in system RAM ("Non Local Usage"):
           when the card is full this is the spill, and it is why a model got slow.
  A trailing * means the resident counter had no row and the WDDM COMMIT is shown instead
  (Task Manager's column; commit can legitimately exceed physical VRAM).
  Adapter "VRAM x/y" is resident usage from the adapter's own counter; the rows will not sum
  to it exactly (driver/system reservations, shared surfaces). Engine %% needs two reads.

AGENTS
  fastest read:   vramtop --json --no-util          (~150 ms, memory only)
  typical read:   vramtop --json                    (~600 ms, includes engine load)
  receipt:        vramtop --stamp                   (embed the line in your timing row)
  stream:         vramtop --json --watch --frames 10 -n 2000
  MCP server:     claude mcp add vramtop -- C:/GPUz/vramtop.exe --mcp
  JSON shape: {"adapters":[{index,name,vendor,luid,vram_total_bytes,vram_used_bytes,
    vram_budget_bytes,shared_*,sysmem_used_bytes,util_pct,engines[{name,pct}],temp_c,fan_rpm,
    power_pct,mem_clock_mhz,...}], "processes":[{pid,adapter,name,path,vram_resident_bytes|null,
    vram_committed_bytes,vram_bytes,sysmem_bytes,shared_bytes,util_pct,top_engine}]}
    (vram_bytes = resident, else committed; sample_ms = measured window, 0 = no load data)

EXIT CODES   0 ok · 1 bad arguments · 2 collector error (JSON still emitted) · 3 selftest failed
)";

// True only for a real double-click launch: our own fresh console, or no console
// AND no usable stdout (agent harnesses run us console-less with stdout piped —
// they must always get text, never a blocking window).
static bool fresh_own_console() {
    if (GetConsoleWindow() != nullptr) {
        DWORD pids[4];
        return GetConsoleProcessList(pids, 4) <= 1;
    }
    HANDLE h = GetStdHandle(STD_OUTPUT_HANDLE);
    const DWORD t = (h && h != INVALID_HANDLE_VALUE) ? GetFileType(h) : FILE_TYPE_UNKNOWN;
    return t != FILE_TYPE_PIPE && t != FILE_TYPE_DISK && t != FILE_TYPE_CHAR;
}

static int arg_num(int argc, char** argv, int& i, const char* flag) {
    if (i + 1 >= argc) {
        fprintf(stderr, "vramtop: %s needs a value\n", flag);
        exit(1);
    }
    return atoi(argv[++i]);
}
static const char* arg_str(int argc, char** argv, int& i, const char* flag) {
    if (i + 1 >= argc) {
        fprintf(stderr, "vramtop: %s needs a value\n", flag);
        exit(1);
    }
    return argv[++i];
}

// --about: the organ describes itself as one JSON object — the contract `peek env` reads so the
// machine map asks the tools instead of hardcoding them (name, verbs, MCP, health, docs).
static int run_about() {
    char exe[MAX_PATH * 2] = "";
    GetModuleFileNameA(nullptr, exe, (DWORD)sizeof exe);
    std::string dir(exe);
    dir = dir.substr(0, dir.find_last_of('\\') + 1);
    Snapshot s = collect(0, false);
    std::string adapters;
    size_t n = 0;
    for (const auto& a : s.adapters) {
        if (a.vram_total == 0 && a.vram_used == 0) continue;
        if (n++) adapters += ", ";
        adapters += a.name + " (" + human_bytes(a.vram_used) + " of " + human_bytes(a.vram_total) + " resident)";
    }
    std::string j = "{\"organ\":\"vramtop\",\"version\":" + jstr(kVersion) + ",\"path\":" + jstr(exe) + ",\"family\":\"everything/facet · everywhere · everywhen · vramtop · everywho\"";
    j += ",\"purpose\":\"who holds the GPU: per-process VRAM resident, committed and spilled to system RAM, engine load per process, the whole card as a treemap (a Task Manager for the GPU)\"";
    j += ",\"verbs\":[";
    j += "{\"verb\":\"vramtop\",\"what\":\"one snapshot: adapters, then every process holding VRAM\",\"example\":\"vramtop\"},";
    j += "{\"verb\":\"vramtop -w\",\"what\":\"live TUI (q s g p)\",\"example\":\"vramtop -w\"},";
    j += "{\"verb\":\"vramtop -j\",\"what\":\"one JSON snapshot; -j -w = NDJSON\",\"example\":\"vramtop -j --no-util\"},";
    j += "{\"verb\":\"vramtop --stamp\",\"what\":\"one-line co-tenancy receipt: free MiB, budget, spill, tenants\",\"example\":\"vramtop --stamp\"},";
    j += "{\"verb\":\"vramtop --spool\",\"what\":\"change-gated lane<TAB>text stream (lane gpu)\",\"example\":\"vramtop --spool\"},";
    j += "{\"verb\":\"vramtop --gui\",\"what\":\"the treemap window (vramtopw.exe = no console)\",\"example\":\"vramtopw.exe\"}";
    j += "]";
    j += ",\"mcp\":{\"command\":" + jstr(exe) + ",\"args\":[\"--mcp\"],\"tools\":[\"gpu_snapshot\",\"gpu_stamp\"],\"register\":" + jstr(std::string("claude mcp add vramtop -- ") + exe + " --mcp") + "}";
    j += ",\"health\":{\"ok\":" + std::string(s.error.empty() && n ? "true" : "false") + ssprintf(",\"adapters\":%zu", n) + ",\"detail\":" +
         jstr(s.error.empty() ? (n ? adapters : std::string("no adapter with VRAM reported")) : s.error) + "}";
    j += ",\"docs\":" + jstr(dir + "README.md") + ",\"tape\":null}\n";
    fwrite(j.data(), 1, j.size(), stdout);
    return s.error.empty() ? 0 : 2;
}

int app_main(int argc, char** argv) {
    Opts o;
    for (int i = 1; i < argc; ++i) {
        const std::string a = argv[i];
        if (a == "-w" || a == "--watch") o.mode = Opts::Mode::Watch;
        else if (a == "-j" || a == "--json") o.json = true;
        else if (a == "--gui") o.mode = Opts::Mode::Gui;
        else if (a == "--mcp") o.mode = Opts::Mode::Mcp;
        else if (a == "--spool") o.mode = Opts::Mode::Spool;
        else if (a == "--stamp") o.mode = Opts::Mode::Stamp;
        else if (a == "--selftest") o.mode = Opts::Mode::Selftest;
        else if (a == "--about") o.mode = Opts::Mode::About;
        else if (a == "-h" || a == "--help" || a == "/?") o.mode = Opts::Mode::Help;
        else if (a == "-v" || a == "--version") o.mode = Opts::Mode::Version;
        else if (a == "--sample-ms") { o.sample_ms = (uint32_t)std::clamp(arg_num(argc, argv, i, "--sample-ms"), 0, 10000); o.sample_ms_set = true; }
        else if (a == "--no-util") { o.sample_ms = 0; o.sample_ms_set = true; }
        else if (a == "-n" || a == "--interval") o.interval_ms = (uint32_t)std::clamp(arg_num(argc, argv, i, "--interval"), 100, 3600000);
        else if (a == "--frames") o.frames = std::clamp(arg_num(argc, argv, i, "--frames"), 0, 1000000);
        else if (a == "--top") o.top = std::clamp(arg_num(argc, argv, i, "--top"), 0, 10000);
        else if (a == "--min-mb") o.min_mb = std::max(0.0, atof(arg_str(argc, argv, i, "--min-mb")));
        else if (a == "-g" || a == "--group") o.group = true;
        else if (a == "--plain") o.plain = true;
        else if (a == "--no-procs") o.no_procs = true;
        else if (a == "--adapter") o.adapter = arg_num(argc, argv, i, "--adapter");
        else if (a == "--spool-file") o.spool_file = arg_str(argc, argv, i, "--spool-file");
        else if (a == "--lane") o.lane = arg_str(argc, argv, i, "--lane");
        else if (a == "--gate-mb") o.gate_mb = std::max(0.0, atof(arg_str(argc, argv, i, "--gate-mb")));
        else if (a == "--gate-pct") o.gate_pct = std::max(0.0, atof(arg_str(argc, argv, i, "--gate-pct")));
        else if (a == "--sort") {
            const std::string v = arg_str(argc, argv, i, "--sort");
            if (v == "vram") o.sort = Opts::Sort::Vram;
            else if (v == "sysmem" || v == "spill") o.sort = Opts::Sort::Sysmem;
            else if (v == "util") o.sort = Opts::Sort::Util;
            else if (v == "pid") o.sort = Opts::Sort::Pid;
            else if (v == "name") o.sort = Opts::Sort::Name;
            else { fprintf(stderr, "vramtop: unknown sort '%s'\n", v.c_str()); return 1; }
        } else {
            fprintf(stderr, "vramtop: unknown option '%s' (try --help)\n", a.c_str());
            return 1;
        }
    }

    const bool auto_gui = o.mode == Opts::Mode::Auto && !o.json && fresh_own_console();
    if (o.mode == Opts::Mode::Gui || auto_gui) {
        if (fresh_own_console()) FreeConsole();
        return run_gui(o);
    }
    ensure_console_for_text();

    switch (o.mode) {
        case Opts::Mode::Help:
            if (stdout_is_console()) SetConsoleOutputCP(CP_UTF8);
            printf(kHelp, kVersion);
            return 0;
        case Opts::Mode::Version: printf("vramtop %s\n", kVersion); return 0;
        case Opts::Mode::Mcp: return run_mcp();
        case Opts::Mode::Spool: return run_spool(o);
        case Opts::Mode::Stamp: return run_stamp(o);
        case Opts::Mode::About: return run_about();
        case Opts::Mode::Selftest: { console_setup(o); return run_selftest(); }
        case Opts::Mode::Watch:
            if (o.json) return run_ndjson(o);
            return run_watch(o);
        default: {
            if (o.json) {
                Snapshot s = collect(o.sample_ms, !o.no_procs);
                std::string j = to_json(s, o.min_mb, o.top);
                j += "\n";
                fwrite(j.data(), 1, j.size(), stdout);
                return s.error.empty() ? 0 : 2;
            }
            console_setup(o);
            Snapshot s = collect(o.sample_ms, !o.no_procs);
            RenderCtx rc;
            rc.ansi = !o.plain && g_vt_enabled;
            rc.width = console_width();
            const std::string out = render(s, o, rc);
            fwrite(out.data(), 1, out.size(), stdout);
            return s.error.empty() ? 0 : 2;
        }
    }
}

}  // namespace vramtop

int main(int argc, char** argv) { return vramtop::app_main(argc, argv); }