muonroi-cli 1.8.4 → 1.8.5

package/LICENSE

@@ -1,9 +1,21 @@
-Copyright (c) 2026 muonroi. All rights reserved.
+MIT License
 
-Commercial / Proprietary License
+Copyright (c) 2026 muonroi
 
-This software and associated documentation files (the "Software") are proprietary to muonroi.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-Unauthorized copying, modification, distribution, transmission, performance, display or other use of this Software, via any medium, is strictly prohibited.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
-The Software is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/packages/agent-harness-core/src/driver.d.ts

@@ -1,5 +1,13 @@
 import { type Predicate } from "./predicate.js";
-import type { LiveEvent, LiveFrame, UINode } from "./protocol.js";
+import type { LiveEvent, LiveFrame, UINode, VisualFrame } from "./protocol.js";
+import { type VisualQualityReport } from "./visual-quality.js";
+/** A single decoded cell from the rendered grid (returned by `visual_cell`). */
+export type VisualCell = {
+    char: string;
+    fg: string;
+    bg: string;
+    attrs: number;
+};
 type WaitConditionIdle = {
     idle: true;
 };
@@ -31,6 +39,9 @@ type DriverDeps = {
 type Ingested = {
     kind: "frame";
     frame: LiveFrame;
+} | {
+    kind: "visual";
+    frame: VisualFrame;
 } | {
     kind: "idle";
 } | {
@@ -69,6 +80,21 @@ export type Driver = {
      */
     events: (filter?: EventFilter) => AsyncIterable<LiveEvent>;
     render_text: () => string;
+    /** Latest VisualFrame — the ACTUAL rendered cell grid (colors + attributes),
+     *  or null if the TUI has not emitted one (renderer not attached). */
+    snapshot_visual: () => VisualFrame | null;
+    /** Render the visual grid as plain text (what a human reads on screen) —
+     *  faithful to the rendered characters, unlike render_text (semantic tree). */
+    render_visual: () => string;
+    /** Decode the cell at (row, col) — char + fg/bg hex + attribute bits — from
+     *  the latest VisualFrame, accounting for wide (2-col) glyphs. Null if out of
+     *  range or no visual frame yet. */
+    visual_cell: (row: number, col: number) => VisualCell | null;
+    /** Programmatic visual-quality heuristics over the latest VisualFrame:
+     *  near-empty-row ratio, blank-row runs, whitespace density, and mojibake —
+     *  the exact "messy render" signals the semantic tree is blind to. Null if no
+     *  visual frame yet. */
+    visual_quality: () => VisualQualityReport | null;
     _ingest: (m: Ingested) => void;
     /** Called when the TUI exits. Cleanly terminates all active `events()` iterables. */
     _closeAllSubscribers: () => void;

package/dist/packages/agent-harness-core/src/driver.js

@@ -1,5 +1,6 @@
 import { evaluatePredicate, predicateSchema } from "./predicate.js";
 import { matchSelector } from "./selector.js";
+import { computeVisualQuality } from "./visual-quality.js";
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -12,6 +13,7 @@ const PER_SUBSCRIBER_QUEUE_CAP = 256;
 // ---------------------------------------------------------------------------
 export function createDriver(deps) {
     let latestFrame = null;
+    let latestVisualFrame = null;
     let lastIdleAt = -1;
     const eventBuffer = [];
     const waiters = new Set();
@@ -276,10 +278,54 @@ export function createDriver(deps) {
                 return "(no frame)";
             return latestFrame.nodes.map((n) => renderNode(n, 0)).join("\n");
         },
+        snapshot_visual() {
+            return latestVisualFrame;
+        },
+        render_visual() {
+            if (!latestVisualFrame)
+                return "(no visual frame)";
+            return latestVisualFrame.lines
+                .map((ln) => ln.spans
+                .map((s) => s.text)
+                .join("")
+                .replace(/\s+$/, ""))
+                .join("\n");
+        },
+        visual_cell(row, col) {
+            const frame = latestVisualFrame;
+            if (!frame)
+                return null;
+            const line = frame.lines[row];
+            if (!line)
+                return null;
+            // Walk spans accumulating display columns; a wide glyph spans 2 columns
+            // but its span.width already reflects that, so index within the run by
+            // string position while tracking the column cursor.
+            let colCursor = 0;
+            for (const span of line.spans) {
+                const chars = [...span.text];
+                for (const ch of chars) {
+                    // A char occupies span.width / chars.length columns on average; for
+                    // the common width===text-length case this is 1. Round to stay integral.
+                    const chCols = Math.max(1, Math.round(span.width / Math.max(1, chars.length)));
+                    if (col >= colCursor && col < colCursor + chCols) {
+                        return { char: ch, fg: span.fg, bg: span.bg, attrs: span.attrs };
+                    }
+                    colCursor += chCols;
+                }
+            }
+            return null;
+        },
+        visual_quality() {
+            return latestVisualFrame ? computeVisualQuality(latestVisualFrame) : null;
+        },
         _ingest(m) {
             if (m.kind === "frame") {
                 latestFrame = m.frame;
             }
+            else if (m.kind === "visual") {
+                latestVisualFrame = m.frame;
+            }
             else if (m.kind === "idle") {
                 lastIdleAt = Date.now();
             }

package/dist/packages/agent-harness-core/src/event-tee.d.ts

@@ -0,0 +1,48 @@
+/**
+ * event-tee.ts — optional JSONL sink for harness LiveEvents.
+ *
+ * Why: the MCP wake mechanism that re-invokes an external agent is a background
+ * task (e.g. a milestone watcher), which is a SEPARATE process from the MCP
+ * server. That watcher can only read files — it cannot reach the in-process
+ * driver that holds the real UI. So a generic, reusable milestone watcher needs
+ * the harness to persist events to a file it can tail.
+ *
+ * The DB only records debate-END rows (synthesis/debate_complete), so a
+ * DB-poll watcher is blind to mid-flight modal pauses (askcard-open) that never
+ * write a DB row. Teeing every LiveEvent to a JSONL file closes that gap for
+ * ANY event kind.
+ *
+ * Ephemeral events (toast, disconnect, retry, ee-*) flash and vanish before an
+ * agent can wake + render, so for those kinds — and ONLY those — we attach a
+ * plain-text visual snapshot captured at emit time, so the watcher's wake
+ * payload carries the exact frame. Persistent states (askcard, post-debate
+ * card) stay put, so the agent renders them fresh on demand; embedding a stale
+ * snapshot for those would be worse, not better.
+ *
+ * Gated entirely behind MUONROI_HARNESS_EVENT_LOG — unset means zero behavior
+ * change (clean checkouts are byte-identical to before this file existed).
+ */
+import type { LiveEvent } from "./protocol.js";
+/**
+ * Event kinds that flash and disappear before an agent can wake + render.
+ * Only these carry an at-emit visual snapshot in the teed line.
+ */
+export declare const EPHEMERAL_KINDS: ReadonlySet<string>;
+/** One teed JSONL record. */
+export interface TeedEventLine {
+    ts: number;
+    kind: string;
+    event: LiveEvent;
+    /** Present only for EPHEMERAL_KINDS — plain-text visual frame at emit time. */
+    visualText?: string;
+}
+/**
+ * Build an event-tee sink. Returns null when MUONROI_HARNESS_EVENT_LOG is unset
+ * or blank (no-op path — caller skips it entirely).
+ *
+ * @param getVisualText - lazily renders the current visual frame to plain text
+ *   (driver.render_visual). Called ONLY for ephemeral kinds, so persistent
+ *   events pay nothing.
+ * @param envValue - value of MUONROI_HARNESS_EVENT_LOG (injectable for tests).
+ */
+export declare function createEventTee(getVisualText: () => string | null, envValue?: string): ((event: LiveEvent) => void) | null;

package/dist/packages/agent-harness-core/src/event-tee.js

@@ -0,0 +1,77 @@
+/**
+ * event-tee.ts — optional JSONL sink for harness LiveEvents.
+ *
+ * Why: the MCP wake mechanism that re-invokes an external agent is a background
+ * task (e.g. a milestone watcher), which is a SEPARATE process from the MCP
+ * server. That watcher can only read files — it cannot reach the in-process
+ * driver that holds the real UI. So a generic, reusable milestone watcher needs
+ * the harness to persist events to a file it can tail.
+ *
+ * The DB only records debate-END rows (synthesis/debate_complete), so a
+ * DB-poll watcher is blind to mid-flight modal pauses (askcard-open) that never
+ * write a DB row. Teeing every LiveEvent to a JSONL file closes that gap for
+ * ANY event kind.
+ *
+ * Ephemeral events (toast, disconnect, retry, ee-*) flash and vanish before an
+ * agent can wake + render, so for those kinds — and ONLY those — we attach a
+ * plain-text visual snapshot captured at emit time, so the watcher's wake
+ * payload carries the exact frame. Persistent states (askcard, post-debate
+ * card) stay put, so the agent renders them fresh on demand; embedding a stale
+ * snapshot for those would be worse, not better.
+ *
+ * Gated entirely behind MUONROI_HARNESS_EVENT_LOG — unset means zero behavior
+ * change (clean checkouts are byte-identical to before this file existed).
+ */
+import { appendFileSync } from "node:fs";
+/**
+ * Event kinds that flash and disappear before an agent can wake + render.
+ * Only these carry an at-emit visual snapshot in the teed line.
+ */
+export const EPHEMERAL_KINDS = new Set([
+    "toast",
+    "disconnect",
+    "stream-retry",
+    "ee-timeout",
+    "ee-error",
+    "grounding-flag",
+]);
+/**
+ * Build an event-tee sink. Returns null when MUONROI_HARNESS_EVENT_LOG is unset
+ * or blank (no-op path — caller skips it entirely).
+ *
+ * @param getVisualText - lazily renders the current visual frame to plain text
+ *   (driver.render_visual). Called ONLY for ephemeral kinds, so persistent
+ *   events pay nothing.
+ * @param envValue - value of MUONROI_HARNESS_EVENT_LOG (injectable for tests).
+ */
+export function createEventTee(getVisualText, envValue) {
+    const path = (envValue ?? "").trim();
+    if (!path)
+        return null;
+    return (event) => {
+        // The idle sentinel arrives as { t: "idle" } — never here. Guard anyway so
+        // a malformed event can't crash the ingest loop.
+        const kind = event.kind;
+        if (typeof kind !== "string")
+            return;
+        const line = { ts: Date.now(), kind, event };
+        if (EPHEMERAL_KINDS.has(kind)) {
+            try {
+                const visual = getVisualText();
+                if (visual)
+                    line.visualText = visual;
+            }
+            catch (err) {
+                // A visual-render failure must not drop the event record itself.
+                console.error(`[event-tee] visual snapshot failed for kind=${kind}: ${err?.message}`);
+            }
+        }
+        try {
+            appendFileSync(path, `${JSON.stringify(line)}\n`);
+        }
+        catch (err) {
+            console.error(`[event-tee] append failed (path=${path}, kind=${kind}): ${err?.message}`);
+        }
+    };
+}
+//# sourceMappingURL=event-tee.js.map

package/dist/packages/agent-harness-core/src/mcp-server.d.ts

@@ -13,6 +13,7 @@
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { type Driver } from "./driver.js";
+import type { LiveEvent } from "./protocol.js";
 /**
  * The result returned by a HarnessSpawn implementation.
  * Both the POSIX fd-3/4 and Windows named-pipe transports satisfy this shape.
@@ -95,6 +96,16 @@ export declare function registerAsyncTools(server: McpServer, getDriver: () => D
 export declare function createMcpHarnessServer({ spawn }: {
     spawn: HarnessSpawn;
 }): McpServer;
+/**
+ * Build the onLine sidechannel handler: parse each JSON line, ingest frames /
+ * visuals / idle / events into the driver, and tee events to the optional JSONL
+ * sink. Extracted (and exported) so the frame/event/tee wiring is unit-testable
+ * without a live TUI or an MCP protocol handshake.
+ *
+ * @param driver   the driver to ingest into (only _ingest is used).
+ * @param eventTee optional sink from createEventTee (null → no tee).
+ */
+export declare function makeLineHandler(driver: Pick<Driver, "_ingest">, eventTee: ((event: LiveEvent) => void) | null): (line: string) => void;
 /**
  * Run the MCP harness driver over stdio with the OpenTUI spawn implementation
  * injected by the consumer.

package/dist/packages/agent-harness-core/src/mcp-server.js

@@ -18,6 +18,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { createDriver } from "./driver.js";
+import { createEventTee } from "./event-tee.js";
 import { PROTOCOL_VERSION } from "./protocol.js";
 const ARG_ALLOW = /^(--agent-[a-z-]+(=.*)?|--mock-llm(=.+)?|--profile=[a-zA-Z0-9_-]+)$/;
 const ENV_KEY_RE = /^[A-Z_][A-Z0-9_]{0,63}$/;
@@ -133,7 +134,20 @@ export function validateMockLlmPath(value) {
     const sep = process.platform === "win32" ? "\\" : "/";
     return real === root || real.startsWith(root + sep);
 }
-const FEATURES = ["capabilities", "snapshot", "press", "type", "wait_for", "query", "expect", "render_text"];
+const FEATURES = [
+    "capabilities",
+    "snapshot",
+    "press",
+    "type",
+    "wait_for",
+    "query",
+    "expect",
+    "render_text",
+    "render_visual",
+    "snapshot_visual",
+    "cell",
+    "visual_quality",
+];
 export function buildCapabilitiesPayload() {
     return {
         protocol: PROTOCOL_VERSION,
@@ -203,6 +217,42 @@ export function registerReadTools(server, getDriver) {
             return noDriver();
         return { content: [{ type: "text", text: d.render_text() }] };
     });
+    server.registerTool("tui.render_visual", {
+        description: "Render the ACTUAL rendered cell grid as plain text — the characters a human reads on screen. Unlike tui.render_text (semantic tree), this reflects the real render. Requires agent-mode with the renderer attached.",
+        inputSchema: {},
+    }, async () => {
+        const d = getDriver();
+        if (!d)
+            return noDriver();
+        return { content: [{ type: "text", text: d.render_visual() }] };
+    });
+    server.registerTool("tui.snapshot_visual", {
+        description: "Return the latest VisualFrame — the real rendered cell grid with per-cell char + fg/bg hex + attribute bits. null until the renderer emits one.",
+        inputSchema: {},
+    }, async () => {
+        const d = getDriver();
+        if (!d)
+            return noDriver();
+        return { content: [{ type: "text", text: JSON.stringify(d.snapshot_visual()) }] };
+    });
+    server.registerTool("tui.cell", {
+        description: "Decode the rendered cell at (row, col): char + fg/bg hex + attribute bits, from the latest VisualFrame. Use to assert the colors/formatting a human actually sees.",
+        inputSchema: { row: z.number().int().min(0), col: z.number().int().min(0) },
+    }, async ({ row, col }) => {
+        const d = getDriver();
+        if (!d)
+            return noDriver();
+        return { content: [{ type: "text", text: JSON.stringify(d.visual_cell(row, col)) }] };
+    });
+    server.registerTool("tui.visual_quality", {
+        description: "Heuristic visual-quality report over the rendered grid: near-empty-row ratio, blank-row runs, whitespace density, mojibake, a 0-100 score and issues[]. Catches 'messy render' the semantic tree cannot see.",
+        inputSchema: {},
+    }, async () => {
+        const d = getDriver();
+        if (!d)
+            return noDriver();
+        return { content: [{ type: "text", text: JSON.stringify(d.visual_quality()) }] };
+    });
 }
 export function registerActionTools(server, getDriver) {
     const noDriver = () => ({
@@ -459,22 +509,13 @@ export function createMcpHarnessServer({ spawn }) {
             sendKey: (k) => sendLine(JSON.stringify({ op: "press", key: k })),
             sendType: (t) => sendLine(JSON.stringify({ op: "type", text: t })),
         });
+        // Optional JSONL event sink for external milestone watchers (null unless
+        // MUONROI_HARNESS_EVENT_LOG is set). Ephemeral kinds carry an at-emit
+        // visual snapshot so flash events aren't lost before an agent wakes.
+        const eventTee = createEventTee(() => driver.render_visual(), process.env["MUONROI_HARNESS_EVENT_LOG"]);
         // onLine already delivers complete newline-stripped lines — no extra
         // splitting required.
-        const unsub = onLine((line) => {
-            try {
-                const msg = JSON.parse(line);
-                if (msg.mode === "live")
-                    driver._ingest({ kind: "frame", frame: msg });
-                else if (msg.t === "idle")
-                    driver._ingest({ kind: "idle" });
-                else if (msg.t === "event")
-                    driver._ingest({ kind: "event", event: msg });
-            }
-            catch {
-                // ignore malformed lines
-            }
-        });
+        const unsub = onLine(makeLineHandler(driver, eventTee));
         spawnResult.exited.then(() => {
             unsub();
             if (currentPid === proc.pid) {
@@ -491,6 +532,37 @@ export function createMcpHarnessServer({ spawn }) {
     registerAsyncTools(server, () => currentDriver, { onStop });
     return server;
 }
+/**
+ * Build the onLine sidechannel handler: parse each JSON line, ingest frames /
+ * visuals / idle / events into the driver, and tee events to the optional JSONL
+ * sink. Extracted (and exported) so the frame/event/tee wiring is unit-testable
+ * without a live TUI or an MCP protocol handshake.
+ *
+ * @param driver   the driver to ingest into (only _ingest is used).
+ * @param eventTee optional sink from createEventTee (null → no tee).
+ */
+export function makeLineHandler(driver, eventTee) {
+    return (line) => {
+        try {
+            const msg = JSON.parse(line);
+            if (msg.mode === "live")
+                driver._ingest({ kind: "frame", frame: msg });
+            else if (msg.mode === "visual")
+                driver._ingest({ kind: "visual", frame: msg });
+            else if (msg.t === "idle")
+                driver._ingest({ kind: "idle" });
+            else if (msg.t === "event") {
+                const event = msg;
+                driver._ingest({ kind: "event", event });
+                // Tee AFTER ingest so render_visual reflects the frame at this event.
+                eventTee?.(event);
+            }
+        }
+        catch {
+            // ignore malformed lines
+        }
+    };
+}
 /**
  * Run the MCP harness driver over stdio with the OpenTUI spawn implementation
  * injected by the consumer.

package/dist/packages/agent-harness-core/src/protocol.d.ts

@@ -1,5 +1,17 @@
 export declare const PROTOCOL_VERSION: "0.4.0";
-export type Role = "dialog" | "textbox" | "listbox" | "listitem" | "button" | "checkbox" | "radio" | "radiogroup" | "tab" | "tablist" | "tree" | "treeitem" | "table" | "row" | "cell" | "progressbar" | "spinner" | "log" | "statusbar" | "menu" | "menuitem" | "toast" | "tooltip" | "region";
+/**
+ * Known accessibility-style roles for semantic blocks. Closed vocabulary —
+ * `Role` (below) additionally admits namespaced `x-*` custom roles so new UI
+ * surfaces can be introduced without a protocol version bump (additive-only).
+ */
+export type KnownRole = "dialog" | "textbox" | "listbox" | "listitem" | "button" | "checkbox" | "radio" | "radiogroup" | "tab" | "tablist" | "tree" | "treeitem" | "table" | "row" | "cell" | "progressbar" | "spinner" | "log" | "statusbar" | "menu" | "menuitem" | "toast" | "tooltip" | "region" | "editor" | "diff" | "gutter" | "panel";
+/**
+ * A semantic role. Either a well-known {@link KnownRole} or a namespaced
+ * `x-<custom>` role. The `x-` prefix keeps custom roles greppable and prevents
+ * silent collisions with future well-known roles — additive versioning via the
+ * `tui.capabilities` handshake rather than a breaking protocol bump.
+ */
+export type Role = KnownRole | `x-${string}`;
 export type UINode = {
     id: string;
     role: Role;
@@ -23,6 +35,58 @@ export type LiveFrame = {
     modals?: string[];
     nodes: UINode[];
 };
+/**
+ * Text-attribute bit flags in {@link VisualSpan.attrs}. Mirrors the low byte of
+ * OpenTUI's `TextAttributes` (`ATTRIBUTE_BASE_MASK = 255`), so a consumer can
+ * decode `attrs & VisualAttr.BOLD` etc. without importing the renderer.
+ */
+export declare const VisualAttr: {
+    readonly BOLD: 1;
+    readonly DIM: 2;
+    readonly ITALIC: 4;
+    readonly UNDERLINE: 8;
+    readonly BLINK: 16;
+    readonly INVERSE: 32;
+    readonly HIDDEN: 64;
+    readonly STRIKETHROUGH: 128;
+};
+/** One coalesced run of identically-styled cells on a visual line. */
+export type VisualSpan = {
+    /** The run's text (wide-char continuation cells omitted; `width` reflects columns). */
+    text: string;
+    /** Foreground color as "#rrggbb" (or "#rrggbbaa" when alpha < 255). */
+    fg: string;
+    /** Background color as "#rrggbb" (or "#rrggbbaa"). */
+    bg: string;
+    /** Text-attribute bitmask — decode with {@link VisualAttr}. */
+    attrs: number;
+    /** Display columns this run occupies (accounts for wide CJK/emoji). */
+    width: number;
+};
+/** One row of the rendered grid, as style-coalesced spans. */
+export type VisualLine = {
+    spans: VisualSpan[];
+};
+/**
+ * Ground-truth snapshot of the ACTUAL rendered terminal cell grid — the real
+ * characters, colors, and attributes OpenTUI painted, read directly from
+ * `CliRenderer.currentRenderBuffer.getSpanLines()`. Unlike {@link LiveFrame}
+ * (semantic structure), this is what a human SEES on screen. No OCR — the cell
+ * buffer is authoritative. Emitted on the same sidechannel as LiveFrame,
+ * deduped by content hash, and (to bound `getSpanLines` allocation) only
+ * captured when a semantic frame also changes.
+ */
+export type VisualFrame = {
+    mode: "visual";
+    version: typeof PROTOCOL_VERSION;
+    seq: number;
+    ts: number;
+    cols: number;
+    rows: number;
+    /** Cursor [col, row], or null when hidden/unknown. */
+    cursor: [number, number] | null;
+    lines: VisualLine[];
+};
 export type LiveEvent = {
     t: "event";
     kind: "stream.delta";
@@ -226,4 +290,4 @@ export type DesignSpec = {
         notes?: string;
     }>;
 };
-export type HarnessMessage = LiveFrame | LiveEvent;
+export type HarnessMessage = LiveFrame | VisualFrame | LiveEvent;

package/dist/packages/agent-harness-core/src/protocol.js

@@ -1,2 +1,17 @@
 export const PROTOCOL_VERSION = "0.4.0";
+/**
+ * Text-attribute bit flags in {@link VisualSpan.attrs}. Mirrors the low byte of
+ * OpenTUI's `TextAttributes` (`ATTRIBUTE_BASE_MASK = 255`), so a consumer can
+ * decode `attrs & VisualAttr.BOLD` etc. without importing the renderer.
+ */
+export const VisualAttr = {
+    BOLD: 1,
+    DIM: 2,
+    ITALIC: 4,
+    UNDERLINE: 8,
+    BLINK: 16,
+    INVERSE: 32,
+    HIDDEN: 64,
+    STRIKETHROUGH: 128,
+};
 //# sourceMappingURL=protocol.js.map

package/dist/packages/agent-harness-core/src/visual-quality.d.ts

@@ -0,0 +1,58 @@
+/**
+ * visual-quality.ts — programmatic visual-quality heuristics over a VisualFrame.
+ *
+ * P1 of Harness TUI v2. Given the ground-truth rendered cell grid, compute cheap
+ * ground-truth signals a human would call "messy" — WITHOUT a vision model:
+ *   - blank / near-blank row ratios (the council "↳" + "· Skip" garbage)
+ *   - long runs of consecutive blank rows (dead space)
+ *   - whitespace density
+ *   - mojibake (U+FFFD replacement chars + misdecoded-UTF8 clusters like `💡`)
+ *
+ * These are the exact defects the semantic tree (LiveFrame) is blind to — the
+ * 2217600e1f27 export had 12 near-empty rows + mojibake that no existing
+ * self-verify check could see. A composite `score` + `issues[]` lets self-QA
+ * fail a render regression automatically.
+ *
+ * Thresholds are conservative defaults; tune per surface. This is a heuristic,
+ * not a proof — a low score flags "look closer", it does not assert a bug.
+ */
+import type { VisualFrame } from "./protocol.js";
+export interface VisualQualityThresholds {
+    /** Rows with <= this many non-space chars count as "near-empty". */
+    nearEmptyMaxChars: number;
+    /** Flag when the near-empty-row ratio exceeds this. */
+    nearEmptyRowPct: number;
+    /** Flag when consecutive blank rows exceed this run length. */
+    maxConsecutiveBlankRows: number;
+    /** Flag when any mojibake is detected at/above this count. */
+    mojibakeCount: number;
+    /** Flag when whitespace density exceeds this fraction. */
+    whitespacePct: number;
+}
+export declare const DEFAULT_VISUAL_QUALITY_THRESHOLDS: VisualQualityThresholds;
+export interface VisualQualityReport {
+    rows: number;
+    cols: number;
+    /** Non-space characters across the whole grid. */
+    contentChars: number;
+    /** Rows that are entirely whitespace. */
+    blankRows: number;
+    /** Rows with 1..nearEmptyMaxChars non-space chars (skeleton noise). */
+    nearEmptyRows: number;
+    nearEmptyRowPct: number;
+    /** Longest run of consecutive fully-blank rows. */
+    maxConsecutiveBlankRows: number;
+    whitespacePct: number;
+    /** Count of mojibake signals (U+FFFD + misdecoded-UTF8 clusters). */
+    mojibakeCount: number;
+    /** Sample of offending text fragments (for diagnostics). */
+    mojibakeSamples: string[];
+    /** 0-100 composite; lower = messier. */
+    score: number;
+    /** Human-readable problems that tripped a threshold. */
+    issues: string[];
+}
+/**
+ * Compute visual-quality signals for a rendered frame. Pure + deterministic.
+ */
+export declare function computeVisualQuality(frame: VisualFrame, thresholds?: VisualQualityThresholds): VisualQualityReport;