Render run output with xterm.js instead of plain text

Replaces the plain-text output <div> with a real xterm.js terminal
(@xterm/xterm + @xterm/addon-fit), so ANSI color/control codes from
scripts render as actual colors instead of raw escape characters.
stderr chunks are wrapped in ANSI red so failures stand out even from
tools that don't colorize their own output. Also sets FORCE_COLOR=1/
CLICOLOR_FORCE=1 as env defaults (real/script env still wins) since
scripts run without a real TTY and most tools auto-disable color
without one of these overrides.

Fixed a React Strict Mode bug found while testing: the initial log was
written to the terminal via a "write once" ref flag in the parent,
but Strict Mode's dev-only mount->cleanup->remount cycle creates a
fresh Terminal on the real mount, so that flag silently skipped
writing to the surviving instance - the terminal looked completely
blank until live output arrived. Fixed by writing initialData inside
the same effect that creates the Terminal, so it's correct by
construction regardless of how many times the effect runs.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

app/package.json

@@ -22,6 +22,8 @@
   "dependencies": {
     "@base-ui/react": "^1.7.0",
     "@hookform/resolvers": "^5.8.0",
+    "@xterm/addon-fit": "^0.11.0",
+    "@xterm/xterm": "^6.0.0",
     "argon2": "^0.45.1",
     "better-sqlite3": "^13.0.3",
     "class-variance-authority": "^0.7.1",

app/src/components/runs/run-terminal.tsx

@@ -1,14 +1,14 @@
 "use client";
 
-import { useEffect, useRef, useState } from "react";
+import { useRef, useState } from "react";
 import { Square } from "lucide-react";
 import { toast } from "sonner";
 import { Button } from "@/components/ui/button";
-import { cn } from "@/lib/utils";
 import { useRunSocket } from "@/hooks/use-run-socket";
 import type { RunStatus } from "@/lib/db/schema";
 import type { ServerMessage } from "@/lib/ws/protocol";
 import { RunStatusBadge } from "./run-status-badge";
+import { XtermView, type XtermViewHandle } from "./xterm-view";
 
 interface RunTerminalProps {
   runId: string;
@@ -17,11 +17,8 @@ interface RunTerminalProps {
   initialExitCode: number | null;
 }
 
-interface Line {
-  key: number;
-  stream: "stdout" | "stderr";
-  text: string;
-}
+const ANSI_RED = "\x1b[31m";
+const ANSI_RESET = "\x1b[0m";
 
 export function RunTerminal({
   runId,
@@ -31,18 +28,17 @@ export function RunTerminal({
 }: RunTerminalProps) {
   const [status, setStatus] = useState<RunStatus>(initialStatus);
   const [exitCode, setExitCode] = useState<number | null>(initialExitCode);
-  const [lines, setLines] = useState<Line[]>(() =>
-    initialLog ? [{ key: -1, stream: "stdout", text: initialLog }] : [],
-  );
-  const bottomRef = useRef<HTMLDivElement>(null);
-  const nextKey = useRef(0);
+  const termRef = useRef<XtermViewHandle>(null);
 
   const { cancel } = useRunSocket(runId, (message: ServerMessage) => {
     if (message.type === "output") {
-      setLines((prev) => [
-        ...prev,
-        { key: nextKey.current++, stream: message.stream, text: message.chunk },
-      ]);
+      // Scripts that colorize their own output (via ANSI codes) render as-is; stderr additionally
+      // gets wrapped in red so failures stand out even from tools that don't colorize themselves.
+      const chunk =
+        message.stream === "stderr"
+          ? `${ANSI_RED}${message.chunk}${ANSI_RESET}`
+          : message.chunk;
+      termRef.current?.write(chunk);
     } else if (message.type === "status") {
       setStatus(message.status);
       setExitCode(message.exitCode ?? null);
@@ -54,10 +50,6 @@ export function RunTerminal({
     }
   });
 
-  useEffect(() => {
-    bottomRef.current?.scrollIntoView({ behavior: "smooth", block: "end" });
-  }, [lines]);
-
   const isActive = status === "queued" || status === "running";
 
   async function handleCancel() {
@@ -85,24 +77,7 @@ export function RunTerminal({
           </Button>
         )}
       </div>
-      <div className="max-h-[60vh] overflow-y-auto rounded-lg bg-zinc-950 p-4 font-mono text-xs leading-relaxed text-zinc-100">
-        {lines.length === 0 ? (
-          <span className="text-zinc-500">Waiting for output...</span>
-        ) : (
-          lines.map((line) => (
-            <div
-              key={line.key}
-              className={cn(
-                "whitespace-pre-wrap break-all",
-                line.stream === "stderr" && "text-red-400",
-              )}
-            >
-              {line.text}
-            </div>
-          ))
-        )}
-        <div ref={bottomRef} />
-      </div>
+      <XtermView ref={termRef} initialData={initialLog} />
     </div>
   );
 }

app/src/components/runs/xterm-view.tsx

@@ -0,0 +1,102 @@
+"use client";
+
+import { forwardRef, useEffect, useImperativeHandle, useRef } from "react";
+import { Terminal } from "@xterm/xterm";
+import { FitAddon } from "@xterm/addon-fit";
+import "@xterm/xterm/css/xterm.css";
+
+export interface XtermViewHandle {
+  write: (data: string) => void;
+}
+
+const theme = {
+  background: "#09090b",
+  foreground: "#f4f4f5",
+  cursor: "#f4f4f5",
+  selectionBackground: "#3f3f46",
+  black: "#18181b",
+  red: "#f87171",
+  green: "#4ade80",
+  yellow: "#facc15",
+  blue: "#60a5fa",
+  magenta: "#c084fc",
+  cyan: "#22d3ee",
+  white: "#e4e4e7",
+  brightBlack: "#3f3f46",
+  brightRed: "#fca5a5",
+  brightGreen: "#86efac",
+  brightYellow: "#fde047",
+  brightBlue: "#93c5fd",
+  brightMagenta: "#d8b4fe",
+  brightCyan: "#67e8f9",
+  brightWhite: "#f4f4f5",
+};
+
+interface XtermViewProps {
+  /** Written into the terminal as soon as it's created. Only read once, on mount. */
+  initialData?: string;
+}
+
+/** A read-only xterm.js instance: interprets ANSI colors/control codes from streamed script
+ * output, unlike a plain <pre> which would just show raw escape characters.
+ *
+ * `initialData` is written inside the same effect that creates the Terminal - not via a
+ * ref call from the parent after the fact - specifically because React's Strict Mode (dev
+ * only) mounts, cleans up, and re-mounts every effect once: a fresh Terminal is created on
+ * each real mount, so a "write once" flag in the parent would write to the first (disposed)
+ * instance and silently skip the surviving one, leaving the terminal blank until the next
+ * live write arrives.
+ */
+export const XtermView = forwardRef<XtermViewHandle, XtermViewProps>(
+  function XtermView({ initialData }, ref) {
+    const containerRef = useRef<HTMLDivElement>(null);
+    const termRef = useRef<Terminal | null>(null);
+
+    useEffect(() => {
+      if (!containerRef.current) return;
+
+      const term = new Terminal({
+        convertEol: true,
+        disableStdin: true,
+        cursorBlink: false,
+        fontSize: 12,
+        lineHeight: 1.4,
+        fontFamily: "ui-monospace, Menlo, monospace",
+        theme,
+      });
+      const fitAddon = new FitAddon();
+      term.loadAddon(fitAddon);
+      term.open(containerRef.current);
+      fitAddon.fit();
+      if (initialData) term.write(initialData);
+      termRef.current = term;
+
+      const resizeObserver = new ResizeObserver(() => {
+        try {
+          fitAddon.fit();
+        } catch {
+          // container has zero size (e.g. mid-layout-shift) - next resize will retry
+        }
+      });
+      resizeObserver.observe(containerRef.current);
+
+      return () => {
+        resizeObserver.disconnect();
+        term.dispose();
+        termRef.current = null;
+      };
+      // eslint-disable-next-line react-hooks/exhaustive-deps -- initialData is intentionally only used on mount
+    }, []);
+
+    useImperativeHandle(ref, () => ({
+      write: (data: string) => termRef.current?.write(data),
+    }));
+
+    return (
+      <div
+        ref={containerRef}
+        className="h-[60vh] overflow-hidden rounded-lg bg-zinc-950 p-2"
+      />
+    );
+  },
+);

app/src/lib/runner/engine.ts

@@ -107,7 +107,16 @@ async function executeRun(
   try {
     const subprocess = execa(script.command, invocation.argv, {
       cwd,
-      env: { ...process.env, ...invocation.env },
+      // Scripts run without a real TTY, so most CLI tools auto-disable color; these are the two
+      // most widely honored override conventions (not universal - true TTY-detecting tools like
+      // GNU coreutils' `--color=auto` still won't colorize without a pty). Real env/script-set
+      // env still win, so this is only a default.
+      env: {
+        FORCE_COLOR: "1",
+        CLICOLOR_FORCE: "1",
+        ...process.env,
+        ...invocation.env,
+      },
       timeout: script.timeoutSeconds * 1000,
       cancelSignal: controller.signal,
       reject: false,