fix(tui): render light theme with readable roles

Author: TheGreatAxios

docs/TUI.md

@@ -134,8 +134,10 @@ titlebar row: the model label sits right-aligned in the top rule as
 `profile · model · effort · mode` (empty segments omitted), and a
 compact `mcp !` sits immediately left of it when any MCP server still needs
 authorization (`/mcp` is the surface that names them), painted in
-`UI.warning` (sand, `#d1ad7d`) — the same role `plugin !` uses. Orange is
-not spent on these standing marks. The brand
+`UI.warning` — the same role `plugin !` uses. Warning is caution gold in the
+dark theme and muted plum (`#655275`) in the light theme; a bronze warning on
+cream is perceptually indistinguishable from machine emphasis, while plum stays
+separate without spending action orange or failure red. The brand
 lockup sits at the left of the bottom rule with the working directory and git
 branch at its right (`AppShell.promptTopRule` / `promptBottomRule`,
 `src/tui/shell/internals.ts`). Context occupancy rides that bottom rule as a percent:
@@ -239,6 +241,13 @@ Ongoing, non-decision status uses the bronze/sand/ember chrome ramp and green
 The one deliberate exception is diff removals, where orange is content (the
 removed line), not a decision marker, and no decision-marker shares that row.
 
+The shell selects its final theme before constructing or mounting renderables.
+An explicit `light` or `dark` setting wins; otherwise `COLORFGBG` wins when it
+identifies the terminal background, then macOS appearance is read synchronously,
+and unknown environments fall back to dark. The macOS read has a 500 ms process
+timeout. Production does not query OSC 11 or switch themes after mount, so the
+first frame cannot mix palettes across transcript, prompt, borders, or overlays.
+
 ## The live task list panel
 
 **Parked pending rebuild.** `formatChromeZones` (`src/tui/chrome-state.ts`)
@@ -418,7 +427,7 @@ framed content in the shell, and their body is shaped rather than merely
 listed (`src/tui/overlay-body.ts`): a dithered header (`░▒▓`) carries the
 subject in the action color — the only Breakthrough Orange on the card. The
 overlay host border and title use calm dim chrome (`UI.textDim`); consequence
-impact in the description zone paints `UI.warning` (sand), not orange. A
+impact in the description zone paints `UI.warning`, not orange. A
 blank row separates the subject from context. Choices are deliberately small:
 each one is a bare, single-line action name (`Reject`, `Accept once`, the
 scope's label) with no consequence text folded into the row. A scope's hint

src/tui/diff-rows.test.ts

@@ -11,7 +11,7 @@ import { toolCallRow } from "./diff";
 import { withTestRenderer, type Harness } from "./harness";
 import { appendStreamRow } from "./shell/chrome";
 import { createAppShell } from "./shell/index";
-import { DIFF_FG } from "./stream";
+import { UI } from "./theme";
 import { toolResultRow } from "./mcp-view";
 
 const WIDE = { width: 100, height: 30 } as const;
@@ -78,8 +78,8 @@ describe("diff transcript rows", () => {
       const spans = spansWithHex(h);
       const del = spans.find((s) => s.text.includes("-") && s.text.length <= 2);
       const add = spans.find((s) => s.text.includes("+") && s.text.length <= 2);
-      expect(del?.fg).toBe(DIFF_FG.del);
-      expect(add?.fg).toBe(DIFF_FG.add);
+      expect(del?.fg).toBe(UI.action);
+      expect(add?.fg).toBe(UI.done);
     }, WIDE);
   });
 
@@ -97,13 +97,13 @@ describe("diff transcript rows", () => {
       const changedAdded = spans.find((s) => s.text.includes("product(a,"));
       const shared = spans.filter((s) => s.text.includes("const"));
 
-      expect(changedRemoved?.fg).toBe(DIFF_FG.del);
-      expect(changedAdded?.fg).toBe(DIFF_FG.add);
+      expect(changedRemoved?.fg).toBe(UI.action);
+      expect(changedAdded?.fg).toBe(UI.done);
       // Bold attribute distinguishes the changed tokens inside the line.
       expect(defined(changedRemoved).attributes).toBeGreaterThan(0);
       // "const" is shared by both sides, so it stays in the context tone.
       expect(shared.length).toBeGreaterThan(0);
-      expect(shared.every((s) => s.fg === DIFF_FG.context)).toBe(true);
+      expect(shared.every((s) => s.fg === UI.textDim)).toBe(true);
     }, WIDE);
   });
 

src/tui/diff.test.ts

@@ -11,7 +11,8 @@ import {
   toolCallRow,
   type DiffLine,
 } from "./diff.js";
-import { DIFF_FG, isDiffRow, isMarkdownRow } from "./stream.js";
+import { isDiffRow, isMarkdownRow } from "./stream.js";
+import { UI } from "./theme.js";
 
 const textOf = (line: DiffLine): string => line.map((seg) => seg.text).join("");
 
@@ -91,19 +92,19 @@ describe("renderDiff", () => {
     const delBody = defined(lines[0]).slice(2);
     const addBody = defined(lines[1]).slice(2);
     const delChanged = delBody
-      .filter((s) => s.fg === DIFF_FG.del)
+      .filter((s) => s.fg === UI.action)
       .map((s) => s.text)
       .join("");
     const addChanged = addBody
-      .filter((s) => s.fg === DIFF_FG.add)
+      .filter((s) => s.fg === UI.done)
       .map((s) => s.text)
       .join("");
     expect(delChanged).toContain("bar");
     expect(addChanged).toContain("baz");
     expect(delChanged).not.toContain("const");
     expect(addChanged).not.toContain("const");
     expect(
-      delBody.some((s) => s.text.includes("const") && s.fg === DIFF_FG.context),
+      delBody.some((s) => s.text.includes("const") && s.fg === UI.textDim),
     ).toBe(true);
   });
 
@@ -118,7 +119,7 @@ describe("renderDiff", () => {
     const lines = renderDiff("a b c", "a x c", 40);
     const changed = defined(lines[0])
       .slice(2)
-      .filter((s) => s.fg === DIFF_FG.del)
+      .filter((s) => s.fg === UI.action)
       .map((s) => s.text.trim())
       .filter(Boolean);
     expect(changed).toEqual(["b"]);
@@ -130,26 +131,26 @@ describe("renderDiff", () => {
     expect(
       defined(removed)
         .slice(1)
-        .every((s) => s.fg === DIFF_FG.del),
+        .every((s) => s.fg === UI.action),
     ).toBe(true);
     expect(
       defined(added)
         .slice(1)
-        .every((s) => s.fg === DIFF_FG.add),
+        .every((s) => s.fg === UI.done),
     ).toBe(true);
   });
 
   test("context rows take the muted context tone", () => {
     const lines = renderDiff("a\nb", "a\nB", 40);
-    expect(defined(lines[0]).every((s) => s.fg === DIFF_FG.context)).toBe(true);
+    expect(defined(lines[0]).every((s) => s.fg === UI.textDim)).toBe(true);
   });
 
   test("line-number column always uses the muted context tone", () => {
     const lines = renderDiff("a\nb", "a\nB", 40);
     expect(lines.map((line) => defined(line[0]).fg)).toEqual([
-      DIFF_FG.context,
-      DIFF_FG.context,
-      DIFF_FG.context,
+      UI.textDim,
+      UI.textDim,
+      UI.textDim,
     ]);
   });
 

src/tui/diff.ts

@@ -16,7 +16,8 @@ import { describeToolCall } from "./tool-formatter.js";
 // The one wrap implementation: a diff row soft-wraps by the same column rules
 // as every other row, so a wide glyph cannot overflow the gutter here alone.
 import { wrapRanges } from "./view/height.js";
-import { DIFF_FG, type StreamRow } from "./stream.js";
+import type { StreamRow } from "./stream.js";
+import { UI } from "./theme.js";
 import { toolArgsView } from "./tool-args.js";
 
 export type DiffRowKind = "add" | "del" | "context";
@@ -139,9 +140,9 @@ const GUTTER: Record<DiffRowKind, string> = {
 };
 
 function rowColor(kind: DiffRowKind): string {
-  if (kind === "add") return DIFF_FG.add;
-  if (kind === "del") return DIFF_FG.del;
-  return DIFF_FG.context;
+  if (kind === "add") return UI.done;
+  if (kind === "del") return UI.action;
+  return UI.textDim;
 }
 
 // Attach each row's position in the old/new file before any collapsing, so a
@@ -227,7 +228,7 @@ export function wordDiffSegments(
   const m = other.length;
   while (i < n && j < m) {
     if (self[i] === other[j]) {
-      out.push({ text: requireDiffLine(self, i), fg: DIFF_FG.context });
+      out.push({ text: requireDiffLine(self, i), fg: UI.textDim });
       i++;
       j++;
     } else if (lcsCell(lcs, i + 1, j) >= lcsCell(lcs, i, j + 1)) {
@@ -351,7 +352,7 @@ export function renderDiff(
           ? [
               {
                 text: idx === 0 ? numCol : " ".repeat(numColWidth),
-                fg: DIFF_FG.context,
+                fg: UI.textDim,
               },
             ]
           : []),
@@ -453,7 +454,7 @@ export function editDiffView(
           [
             {
               text: `… ${all.length - MAX_DIFF_LINES} more diff lines`,
-              fg: DIFF_FG.context,
+              fg: UI.textDim,
             },
           ],
         ]

src/tui/runner/index.ts

@@ -7,6 +7,7 @@
  */
 
 import { EventEmitter } from "node:events";
+import { spawnSync } from "node:child_process";
 import type { Config } from "../../config/index.js";
 import { listFavoriteModels, listRecentModels } from "../../config/settings.js";
 import { isCodexProviderName } from "../../config/codex-providers.js";
@@ -39,8 +40,10 @@ import { createRunnerState, liveAgent } from "./state.js";
 import { applyCredentialRecoverySelection } from "./credential-recovery.js";
 import { setTheme } from "../theme.js";
 import {
+  detectOsAppearance,
   resolveDetectedTheme,
   resolveThemeSetting,
+  sniffSyncTheme,
   syncEnvFromRecord,
 } from "../theme-detect.js";
 import { getLogger } from "@intx/log";
@@ -52,25 +55,36 @@ export function createTUIEventEmitter(): EventEmitter {
 
 export { getTUIRunSummaryStatus } from "../../session/run-sink.js";
 
+function detectStartupOsTheme() {
+  return detectOsAppearance(process.platform, (command, args) => {
+    try {
+      const out = spawnSync(command, [...args], {
+        encoding: "utf8",
+        timeout: 500,
+      });
+      if (out.error !== undefined) return undefined;
+      if (out.status !== 0) return null;
+      return typeof out.stdout === "string" ? out.stdout : undefined;
+    } catch {
+      return undefined;
+    }
+  });
+}
+
 export async function runTUI(initialConfig: Config): Promise<number> {
   const tuiLogger = getLogger([LOG_NAMESPACE_ROOT, "tui"]);
+  const setting = resolveThemeSetting(initialConfig.settings?.theme);
+  const syncEnv = syncEnvFromRecord(process.env);
+  const os =
+    setting === "auto" && sniffSyncTheme(syncEnv) === null
+      ? detectStartupOsTheme()
+      : null;
+  setTheme(resolveDetectedTheme({ setting, syncEnv, os }));
+
   const start = await prepareTUISession(initialConfig, liveTelemetry);
   if (start === null) return 0;
   const state = createRunnerState(start);
 
-  // Sync theme answer (CL-8993): the explicit setting wins, else the
-  // COLORFGBG/TERM_PROGRAM sniff, else dark. Paints correctly on first frame;
-  // the async OS-appearance upgrade in wirePostStartup repaints if it lands
-  // lighter. Unknown terminals stay dark.
-  setTheme(
-    resolveDetectedTheme({
-      setting: resolveThemeSetting(state.config.settings?.theme),
-      syncEnv: syncEnvFromRecord(process.env),
-      osc: null,
-      os: null,
-    }),
-  );
-
   const { pluginModules } = start.trust;
   // /plugins UI backend state: discovered modules plus live, persisted config
   // (enabled flag, credentials, web override, extra paths). Trust grants swap

src/tui/runner/wiring.ts

@@ -7,7 +7,6 @@
  */
 
 import { getLogger } from "@intx/log";
-import { spawnSync } from "node:child_process";
 import {
   loadSettings,
   listFavoriteModels,
@@ -48,19 +47,7 @@ import {
   RESUME_TRANSCRIPT_BLOCK_LIMIT,
   turnsToContentBlocks,
 } from "../turns-to-blocks.js";
-import {
-  setPluginNeedsAttention,
-  setStatusFlash,
-  repaintTranscriptWindow,
-} from "../shell/chrome.js";
-import { UI, setTheme } from "../theme.js";
-import {
-  detectOsAppearance,
-  resolveDetectedTheme,
-  resolveThemeSetting,
-  sniffSyncTheme,
-  syncEnvFromRecord,
-} from "../theme-detect.js";
+import { setPluginNeedsAttention, setStatusFlash } from "../shell/chrome.js";
 import {
   setEffortCycleHandler,
   setMentionSuggestionSource,
@@ -503,39 +490,6 @@ export function wirePostStartup(
       });
     });
 
-  // Async theme upgrade (CL-8993): the sync answer already painted, so a
-  // slower OS-appearance read that disagrees swaps the live binding and
-  // repaints once. Fire-and-forget and spawn-capped — a missing `defaults`
-  // binary abstains to dark rather than stalling startup.
-  void (async () => {
-    const setting = resolveThemeSetting(state.config.settings?.theme);
-    if (setting !== "auto") return;
-    const syncEnv = syncEnvFromRecord(process.env);
-    if (sniffSyncTheme(syncEnv) !== null) return;
-    const os = detectOsAppearance(process.platform, (command, args) => {
-      try {
-        const out = spawnSync(command, [...args], {
-          encoding: "utf8",
-          timeout: 500,
-        });
-        if (out.error !== undefined) return undefined;
-        if (out.status !== 0) return null;
-        return typeof out.stdout === "string" ? out.stdout : undefined;
-      } catch {
-        return undefined;
-      }
-    });
-    const next = resolveDetectedTheme({ setting, syncEnv, osc: null, os });
-    if (next === UI.name) return;
-    setTheme(next);
-    const host = services.hostHolder.instance;
-    if (host !== undefined) repaintTranscriptWindow(host.shell);
-  })().catch((err: unknown) => {
-    tuiLogger.debug("async theme detect failed: {error}", {
-      error: err instanceof Error ? err.message : String(err),
-    });
-  });
-
   if (!state.resumeSkipInitialTask && state.config.task.trim().length > 0) {
     // The operator's initial task, typed as a CLI argument before launch —
     // same provenance as a prompt submit.