muonroi-cli 1.8.4 → 1.9.0

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, resolveEventLogPath } 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}$/;
@@ -49,6 +50,25 @@ export function sanitizeEnv(env) {
     }
     return out;
 }
+/**
+ * Build the child TUI's environment for tui.start.
+ *
+ * Starts from the driver's own env so PATH/HOME survive, overlays the
+ * caller-supplied keys, THEN strips the dangerous ones. The merge-before-strip
+ * order keeps the security posture (NODE_OPTIONS/LD_PRELOAD/… still removed)
+ * while guaranteeing PATH is present: bun drops the fd 3/4 stdio channels when a
+ * child is spawned with a partial env that lacks PATH, which yields a null
+ * inWrite and crashes the whole driver on spawn. `base` defaults to process.env
+ * and is injectable for tests.
+ */
+export function buildChildEnv(callerEnv = {}, base = process.env) {
+    const merged = {};
+    for (const [k, v] of Object.entries(base)) {
+        if (v !== undefined)
+            merged[k] = v;
+    }
+    return sanitizeEnv({ ...merged, ...callerEnv });
+}
 const REPO_ROOT = process.cwd();
 /**
  * Opt-in extra cwd roots for tui.start, layered ON TOP of the default
@@ -133,11 +153,30 @@ 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",
+    "wait_for_event",
+    "event_log",
+];
 export function buildCapabilitiesPayload() {
     return {
         protocol: PROTOCOL_VERSION,
         features: FEATURES,
+        // A default-on sink nobody can locate is still opt-in. Reporting the
+        // resolved path here is what makes it discoverable without the caller
+        // reproducing the env/tmpdir/pid rule.
+        eventLogPath: resolveEventLogPath(process.env["MUONROI_HARNESS_EVENT_LOG"]),
     };
 }
 export function registerReadTools(server, getDriver) {
@@ -197,12 +236,54 @@ export function registerReadTools(server, getDriver) {
             return noDriver();
         return { content: [{ type: "text", text: String(d.count(selector)) }] };
     });
-    server.registerTool("tui.render_text", { description: "ASCII debug render of the current frame.", inputSchema: {} }, async () => {
+    server.registerTool("tui.render_text", {
+        // "debug render" undersold it: this is the primary way to see what is on
+        // screen right now — every node, modal and message in the semantic tree.
+        description: "See the current screen as a semantic tree (every node, modal, message, and focus state). " +
+            "Use tui.render_visual instead for the literal characters a human reads.",
+        inputSchema: {},
+    }, async () => {
         const d = getDriver();
         if (!d)
             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 = () => ({
@@ -268,21 +349,53 @@ export function registerAsyncTools(server, getDriver, deps) {
     const waitConditionShape = {
         selector: z.string().max(500).optional(),
         idle: z.boolean().optional(),
+        event: z.string().max(64).optional(),
     };
+    /**
+     * Rebuild the driver's WaitArgs from validated MCP input.
+     *
+     * Built key-by-key rather than passed through, because the driver dispatches
+     * on `"selector" in args` BEFORE `"event" in args` — an explicitly-`undefined`
+     * `selector` key would still win that check and silently wait on nothing.
+     */
+    function toWaitArgs(c) {
+        if (typeof c.selector === "string")
+            return { selector: c.selector };
+        if (typeof c.event === "string")
+            return { event: c.event };
+        if (c.idle)
+            return { idle: true };
+        return {};
+    }
     server.registerTool("tui.wait_for", {
-        description: "Wait until a selector matches or the TUI is idle (or both for all=).",
+        description: "Block until a selector matches, a LiveEvent of the given kind arrives, or the TUI is idle " +
+            "(all= requires every condition). Prefer this over polling: the wait resolves on the driver's " +
+            "own event stream, so a modal pause (event='askcard-open') or a sprint halt wakes it immediately.",
         inputSchema: {
             selector: z.string().max(500).optional(),
             idle: z.boolean().optional(),
+            // The driver has always supported an `event` condition (buildCheck in
+            // driver.ts); only this MCP schema withheld it, so external agents fell
+            // back to polling a DB that never records askcard-open at all.
+            event: z.string().max(64).optional(),
             all: z.array(z.object(waitConditionShape)).max(10).optional(),
-            timeoutMs: z.number().int().min(0).max(60_000).optional(),
+            // 10 min, matching the longest legitimate single wait (a council debate
+            // phase measured 119.5s, and an unattended /ideal sprint runs longer).
+            // At 60s a caller had to re-issue the wait repeatedly — polling wearing
+            // a wait_for costume.
+            timeoutMs: z.number().int().min(0).max(600_000).optional(),
         },
     }, async (input) => {
         const d = getDriver();
         if (!d)
             return noDriver();
+        const args = input.all
+            ? { all: input.all.map(toWaitArgs) }
+            : toWaitArgs(input);
+        if (typeof input.timeoutMs === "number")
+            args.timeoutMs = input.timeoutMs;
         try {
-            await d.wait_for(input);
+            await d.wait_for(args);
             return { content: [{ type: "text", text: "ok" }] };
         }
         catch (e) {
@@ -305,7 +418,17 @@ export function registerAsyncTools(server, getDriver, deps) {
         return { content: [{ type: "text", text: String(ok) }] };
     });
     server.registerTool("tui.last_event", {
-        description: "Return the most recent event of the given kind (null if none).",
+        // Keyword-loaded on purpose: deferred-tool search matches this text, and
+        // the terse original ("Return the most recent event of the given kind")
+        // did not rank for "is the TUI waiting for input or hung" — the exact
+        // question it answers. An unfindable tool is an absent one.
+        description: "Check what a live run is doing: is it waiting on a human (kind='askcard-open' — the " +
+            "modal/prompt/approval question), what stage it reached (kind='sprint-stage'), did it " +
+            "fail or hang (kind='sprint-halt' / 'toast'), how the council progressed " +
+            "(kind='council-step'). Returns the most recent event of that kind with its FULL payload " +
+            "(null if none) — including the complete askcard question text, which tui.query truncates. " +
+            "Use this instead of polling a database or log file: modal pauses write no DB row, so a " +
+            "poller cannot tell 'waiting for a human' from 'hung'. Pair with tui.wait_for to block.",
         // Full protocol event set (minus the idle sentinel) so an external agent can
         // observe lifecycle events — council/sprint/route/askcard, not just toasts.
         // The Driver accepts any kind; this enum is the MCP-boundary validation.
@@ -423,7 +546,9 @@ export function createMcpHarnessServer({ spawn }) {
                 isError: true,
             };
         }
-        const sanitizedEnv = sanitizeEnv(input.env ?? {});
+        // See buildChildEnv: merge process.env (keeps PATH so bun allocates the
+        // fd 3/4 transport) with caller keys, then strip dangerous vars.
+        const sanitizedEnv = buildChildEnv(input.env ?? {});
         // Build final arg list.
         const finalArgs = [...input.args];
         if (input.mockLlmDir && !finalArgs.some((a) => a.startsWith("--mock-llm"))) {
@@ -459,22 +584,14 @@ export function createMcpHarnessServer({ spawn }) {
             sendKey: (k) => sendLine(JSON.stringify({ op: "press", key: k })),
             sendType: (t) => sendLine(JSON.stringify({ op: "type", text: t })),
         });
+        // JSONL event sink for external milestone watchers — on by default, null
+        // only when MUONROI_HARNESS_EVENT_LOG explicitly disables it. Ephemeral
+        // kinds carry an at-emit visual snapshot so flash events aren't lost
+        // before an agent wakes. Path is reported by tui.capabilities.
+        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 +608,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/predicate.d.ts

@@ -2,8 +2,8 @@ import { z } from "zod";
 import type { UINode } from "./protocol.js";
 declare const FieldOp: z.ZodObject<{
     field: z.ZodEnum<{
-        name: "name";
         value: "value";
+        name: "name";
         state: "state";
     }>;
     op: z.ZodEnum<{

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";
@@ -67,12 +131,34 @@ export type LiveEvent = {
     kind: "council-speaker";
     /** The council role label (e.g. "architect", "security", "qa"). */
     role: string;
-    /** "start" — speaker began their turn; "done" — speaker finished. */
-    status: "start" | "done";
+    /**
+     * "start" — speaker began; "tick" — 1s progress heartbeat (long phases
+     * like research emit these with an advancing `elapsedMs`); "done" —
+     * speaker finished. A harness poller distinguishes ALIVE (tick with
+     * advancing elapsedMs) from HUNG (elapsedMs frozen) via `tui_last_event`.
+     */
+    status: "start" | "tick" | "done";
     /** Round number if available from the status chunk. */
     round?: number;
     /** Correlation ID linking this speaker event to the enclosing council run. */
     correlationId: string;
+    /** Milliseconds elapsed in this speaker's turn/phase; advances on ticks. */
+    elapsedMs?: number;
+    /**
+     * Chars (text + reasoning deltas) streamed since this phase began.
+     * `elapsedMs` can freeze on a HEALTHY call — its tick generator only
+     * advances when the consumer pulls, and a round awaiting its pairs via
+     * Promise.all does not pull. This counter is pushed from the token stream
+     * itself, so growth here proves liveness regardless of pumping.
+     */
+    streamedChars?: number;
+    /**
+     * Age in ms of the most recent stream delta. Small + growing
+     * `streamedChars` = SLOW BUT ALIVE (e.g. a reasoning model emitting
+     * reasoning tokens for minutes before any text); growing age + static
+     * chars = genuinely STUCK.
+     */
+    lastDeltaAgeMs?: number;
 } | {
     t: "event";
     kind: "council-turn-length";
@@ -226,4 +312,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;

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

@@ -0,0 +1,141 @@
+/**
+ * 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.
+ */
+export const DEFAULT_VISUAL_QUALITY_THRESHOLDS = {
+    nearEmptyMaxChars: 2,
+    nearEmptyRowPct: 0.5,
+    maxConsecutiveBlankRows: 4,
+    mojibakeCount: 1,
+    whitespacePct: 0.92,
+};
+// Characters that legitimately never (or almost never) appear in this TUI but
+// are produced when UTF-8 bytes are re-decoded as CP437/latin1. Presence in a
+// 2+ cluster is a strong mojibake signal (e.g. 💡 → "≡ƒÆí", em-dash → "ΓÇô").
+const MOJIBAKE_SIGNAL = new Set([
+    ..."≡ƒÆÇÃÂ’ÿÖÜúÑŒ¬".split(""),
+    "�", // replacement char
+]);
+function rowText(line) {
+    return line.spans.map((s) => s.text).join("");
+}
+function countMojibake(text) {
+    let count = 0;
+    let sample;
+    // Definitive: U+FFFD replacement chars.
+    for (const ch of text) {
+        if (ch === "�")
+            count++;
+    }
+    // Clusters of 2+ consecutive signal chars — mojibake arrives in runs, which
+    // keeps ordinary accented text (single é, ü) from tripping the heuristic.
+    const chars = [...text];
+    let run = 0;
+    for (let i = 0; i <= chars.length; i++) {
+        const isSignal = i < chars.length && MOJIBAKE_SIGNAL.has(chars[i]) && chars[i] !== "�";
+        if (isSignal) {
+            run++;
+        }
+        else {
+            if (run >= 2) {
+                count += run;
+                if (!sample)
+                    sample = chars.slice(Math.max(0, i - run - 4), i + 2).join("");
+            }
+            run = 0;
+        }
+    }
+    return { count, sample };
+}
+/**
+ * Compute visual-quality signals for a rendered frame. Pure + deterministic.
+ */
+export function computeVisualQuality(frame, thresholds = DEFAULT_VISUAL_QUALITY_THRESHOLDS) {
+    const rows = frame.lines.length;
+    const cols = frame.cols;
+    let contentChars = 0;
+    let totalCells = 0;
+    let blankRows = 0;
+    let nearEmptyRows = 0;
+    let maxConsecutiveBlankRows = 0;
+    let curBlankRun = 0;
+    let mojibakeCount = 0;
+    const mojibakeSamples = [];
+    for (const line of frame.lines) {
+        const text = rowText(line);
+        const nonSpace = [...text].filter((c) => c.trim().length > 0).length;
+        contentChars += nonSpace;
+        totalCells += Math.max(text.length, cols);
+        if (nonSpace === 0) {
+            blankRows++;
+            curBlankRun++;
+            maxConsecutiveBlankRows = Math.max(maxConsecutiveBlankRows, curBlankRun);
+        }
+        else {
+            curBlankRun = 0;
+        }
+        // "Low-content" rows = blank OR only a glyph or two (skeleton noise like the
+        // council "↳" / "· Skip" rows, and the blank separators between them). Both
+        // are visual garbage, so they count together against the total row budget.
+        if (nonSpace <= thresholds.nearEmptyMaxChars)
+            nearEmptyRows++;
+        const mj = countMojibake(text);
+        if (mj.count > 0) {
+            mojibakeCount += mj.count;
+            if (mj.sample && mojibakeSamples.length < 5)
+                mojibakeSamples.push(mj.sample);
+        }
+    }
+    // Ratio of low-content (blank or near-empty) rows over the whole frame.
+    const nearEmptyRowPct = rows > 0 ? nearEmptyRows / rows : 0;
+    const whitespacePct = totalCells > 0 ? 1 - contentChars / totalCells : 1;
+    const issues = [];
+    if (nearEmptyRowPct > thresholds.nearEmptyRowPct) {
+        issues.push(`${nearEmptyRows}/${rows} rows are blank or near-empty (<=${thresholds.nearEmptyMaxChars} chars) — skeleton/garbage rows`);
+    }
+    if (maxConsecutiveBlankRows > thresholds.maxConsecutiveBlankRows) {
+        issues.push(`${maxConsecutiveBlankRows} consecutive blank rows — large dead gap`);
+    }
+    if (mojibakeCount >= thresholds.mojibakeCount) {
+        issues.push(`${mojibakeCount} mojibake signal(s) detected (misdecoded UTF-8 / U+FFFD)${mojibakeSamples.length ? ` e.g. ${JSON.stringify(mojibakeSamples[0])}` : ""}`);
+    }
+    if (whitespacePct > thresholds.whitespacePct && contentChars > 0) {
+        issues.push(`${(whitespacePct * 100).toFixed(0)}% of the grid is whitespace — very sparse render`);
+    }
+    // Composite score: start at 100, subtract weighted penalties.
+    let score = 100;
+    score -= Math.min(40, Math.round(nearEmptyRowPct * 60));
+    score -= Math.min(25, Math.max(0, maxConsecutiveBlankRows - thresholds.maxConsecutiveBlankRows) * 4);
+    score -= Math.min(30, mojibakeCount * 6);
+    score -= whitespacePct > thresholds.whitespacePct ? 10 : 0;
+    score = Math.max(0, Math.min(100, score));
+    return {
+        rows,
+        cols,
+        contentChars,
+        blankRows,
+        nearEmptyRows,
+        nearEmptyRowPct,
+        maxConsecutiveBlankRows,
+        whitespacePct,
+        mojibakeCount,
+        mojibakeSamples,
+        score,
+        issues,
+    };
+}
+//# sourceMappingURL=visual-quality.js.map

package/dist/packages/agent-harness-opentui/src/agent-mode.d.ts

@@ -17,6 +17,7 @@
  */
 import type { LiveEvent } from "@muonroi/agent-harness-core/protocol";
 import type { SemanticRegistry } from "./reconciler-hook.js";
+import { type RendererLike } from "./visual-capture.js";
 export type AgentModeOptions = {
     cols: number;
     rows: number;
@@ -40,6 +41,11 @@ export type AgentModeRuntime = {
     onCommand: (h: (cmd: unknown) => void) => void;
     /** Get the current timestamp (real or fake clock). */
     now: () => number;
+    /**
+     * Attach the OpenTUI renderer once it exists (constructed AFTER this runtime
+     * — see src/index.ts). Enables VisualFrame capture of the real cell grid.
+     */
+    attachRenderer: (renderer: RendererLike) => void;
     /** Tear down: close streams, dispose idle detector. */
     dispose: () => void;
 };