magus-cli 0.0.0-placeholder → 7.1.0

package/src/ui/theme-mode.ts

@@ -0,0 +1,440 @@
+import type { ThemeMode } from "@opentui/core";
+
+/**
+ * The one place magus needs to know whether the terminal is light or dark.
+ *
+ * Everything else in the palette avoids this question on purpose: accents are
+ * chosen to clear 3:1 against both backgrounds, and body text uses the terminal's
+ * own foreground. A *disabled row tint* is the exception, because "subtle" is
+ * defined relative to the page — a wash that sits gently on cream is a bright
+ * band on near-black, and there is no third colour that is quiet on both.
+ *
+ * ANSI cannot help here either: there is no alpha channel, so the tint cannot be
+ * expressed as "the page, 8% toward the foreground". OpenTUI's alpha blending
+ * lives only in its 3d module, not the text renderer.
+ *
+ * So we resolve, once at startup, through `theme-resolve.ts`: flag, then
+ * `MAGUS_THEME`, then `TERM_THEME`, then the bounded OSC probe, then
+ * `COLORFGBG`, then dark. **There is no unknown.** Resolution always yields a
+ * mode; when nothing answered it is dark, because that is the user's stated
+ * default, not because dark was detected.
+ */
+
+let detected: ThemeMode = "dark";
+
+/** Set once at startup from `resolveTheme()`. */
+export function setThemeMode(mode: ThemeMode): void {
+	detected = mode;
+}
+
+export function getThemeMode(): ThemeMode {
+	return detected;
+}
+
+/** Test seam — return to the pre-resolution default between cases. */
+export function resetThemeMode(): void {
+	detected = "dark";
+}
+
+/**
+ * Fill for an UNLIT segment of the three-square scope bar.
+ *
+ * The bar reads as three segments, each lit (in its scope colour) or unlit. Unlit
+ * used to be the same mid-grey as body de-emphasis, `#6B7280`, which is dark —
+ * so an unlit segment carried the same visual weight as a lit one and the bar
+ * read as three similar blobs. Reported directly: "non installed state is dark as
+ * well - confusing".
+ *
+ * An unlit segment should recede toward the page, and "toward the page" is the
+ * one thing a fixed colour cannot express: a pale fill that sits quietly on cream
+ * is a bright block on near-black. Hence the two values, chosen per resolved
+ * mode — this is the only place magus asks.
+ */
+export const SCOPE_OFF_FILL = {
+	/** Just off a light page — a filled but quiet segment. */
+	light: "#D9D9CC",
+	/** Just off a dark page. */
+	dark: "#3A3A40",
+} as const;
+
+/** Fill colour for an unlit scope segment. Always a colour — never undefined,
+ *  because the segment is a filled block whatever the terminal turns out to be. */
+export function scopeOffFill(): string {
+	return SCOPE_OFF_FILL[detected];
+}
+
+/**
+ * Badge colours for the four plugin component kinds.
+ *
+ * These are chips, not accents: they sit on hundreds of rows at once, so the
+ * fill has to be a *wash* of the hue rather than the hue itself. That runs into
+ * the same wall `SCOPE_OFF_FILL` documents above — a wash is defined relative to
+ * the page, ANSI has no alpha, so the two ends are picked by hand.
+ *
+ * Hues are deliberately far apart (purple / teal / blue / amber) for the reason
+ * the scope squares are: one character of colour carries no readable hue shift,
+ * only a readable hue *difference*.
+ *
+ * The glyph colour is set per mode too. Reusing the vivid accent over a dark
+ * wash would drop it below the contrast the palette guarantees against the
+ * page — the accent's measured ratio is against `CONTRAST_REFERENCE`, not
+ * against another tint laid on top of it.
+ */
+export const COMPONENT_BADGE = {
+	skill: {
+		light: { bg: "#E9DCF5", fg: "#6B21A8" },
+		dark: { bg: "#2E2140", fg: "#C4A5F0" },
+	},
+	command: {
+		light: { bg: "#D3E7EC", fg: "#0E5F73" },
+		dark: { bg: "#123037", fg: "#7DD3E0" },
+	},
+	agent: {
+		light: { bg: "#DCE4F7", fg: "#1D4ED8" },
+		dark: { bg: "#1B2740", fg: "#A5C0F5" },
+	},
+	mcp: {
+		light: { bg: "#F0E2CE", fg: "#92400E" },
+		dark: { bg: "#3A2A15", fg: "#E5B877" },
+	},
+} as const;
+
+export type ComponentBadgeKind = keyof typeof COMPONENT_BADGE;
+
+/**
+ * Badge and chart colours for the four Claude models, the three external-model slots, and
+ * `inherit`.
+ *
+ * Four strengths, because a badge and a bar cannot share an ink: twenty characters of a
+ * colour weigh far more than six, so what reads as a label reads as a slab when it is a
+ * chart. `bg`/`fg` are the chip; `bar` is the distribution bar's fill; `label` is the ink a
+ * word takes when it is written ON that fill.
+ *
+ * ## Why `label` exists, and why `fg` could not do its job
+ *
+ * A segment of the workflow chart is one block of one colour with its model's name written
+ * on it. The name used to be drawn as the CHIP — `fg` on `bg`, inset into the bar — which
+ * put a second, visibly different rectangle inside a block that is supposed to read as one
+ * thing. Reported exactly that way: "do not add additional background colour to model
+ * segments".
+ *
+ * Deleting the chip and keeping `fg` was not an option: MEASURED, `fg` on the same model's
+ * `bar` runs 1.74:1 (sonnet dark) to 2.99:1 (haiku dark), which is a smudge rather than a
+ * word. `fg` is built to sit on `bg`, and `bg` is not what a bar is painted with.
+ *
+ * So each model owns a fourth ink, chosen against its OWN bar and nothing else. Every one is
+ * the model's own hue taken deep — the same family, not a fifth palette — and every one
+ * clears 4.5:1 with margin; the measured value is on each line below. `inherit` is the one
+ * that runs the other way: its bar is a dark recessive grey rather than a bright mid-tone,
+ * so its label is near-white on the dark page. That is forced by the fill, not a stylistic
+ * exception.
+ *
+ * ## The two pages are built differently, deliberately
+ *
+ * `COMPONENT_BADGE` above explains why a chip needs two ends at all. This map goes one step
+ * further and does not MIRROR them. Cream already carries the light, so a light chip is a
+ * pale wash under mid-tone ink and stays quiet. A near-black page carries none, so the same
+ * construction turns grey and the screen goes flat — a symmetric palette was built, shown,
+ * and rejected on sight as "dark looks like the light theme". A dark chip is therefore a
+ * SATURATED MID-TONE under near-white ink: a wash toward black is dark, a wash toward white
+ * is the light theme, and neither of those is a colour.
+ *
+ * ## The dark fills clear a page we cannot see
+ *
+ * `CONTRAST_REFERENCE_KEYS.dark` is `#1C1C1E`, but a real terminal may be pure black or a
+ * slate like One Dark's `#282C34`. MEASURED, the `COMPONENT_BADGE` dark washes sit at
+ * 1.00–1.07:1 against that slate — the same luminance as the page — so the chip loses its
+ * edge and reads as a hole punched in the row. These fills clear every ground: 3.1–4.3:1 on
+ * black, 2.8–2.9 on slate, and they still clear 4.5:1 on cream, so even a mis-detected theme
+ * is merely odd rather than unreadable.
+ *
+ * Hues stay far apart for the same reason the scope squares' do: one or two characters of
+ * colour carry no readable hue SHIFT, only a readable hue DIFFERENCE.
+ *
+ * ## The mates are ONE hue family, and that is the exception that proves the rule
+ *
+ * `mate1`, `mate2` and `kangaroo` are three different external models, so they need three
+ * distinguishable inks — but they all mean the same thing (someone else's model, reached
+ * through claudish), and four unrelated hues would say the opposite. They therefore share a
+ * warm outback band nothing else on this screen occupies: measured hue angles 39° / 23° / 6°
+ * on the dark page and 41° / 25° / 10° on the light one — ochre, terracotta, red earth. The
+ * four Claude models sit at teal 190°, green 150°, purple 265° and grey, so a mate cannot be
+ * mistaken for one of them at a glance, and a mate cannot be mistaken for another mate
+ * either, because ~17° of hue at full saturation is a readable difference where ~17° of
+ * LUMINANCE would not be.
+ *
+ * Measured contrast, ink on its own fill (the number the chip has to clear):
+ *
+ *   mate1     light 5.60:1   dark 4.82:1
+ *   mate2     light 5.82:1   dark 4.96:1
+ *   kangaroo  light 5.98:1   dark 5.68:1
+ *
+ * And the dark fills against every plausible dark ground — pure black,
+ * `CONTRAST_REFERENCE_KEYS.dark`, One Dark's `#282C34` — plus the cream page a mis-detected
+ * theme would put them on:
+ *
+ *   mate1     4.09 / 3.32 / 2.73   cream 4.81
+ *   mate2     3.83 / 3.10 / 2.55   cream 5.14
+ *   kangaroo  3.31 / 2.68 / 2.21   cream 5.94
+ *
+ * which is the same band the four Claude fills occupy, so a mate chip carries the same weight
+ * as the models beside it rather than reading as a second-class one.
+ *
+ * There is a FOURTH warm entry, `mates`, and it is not a slot: it is the family's own ink,
+ * worn by the one collapsed segment a workflow bar draws for all external work at once. Its
+ * own note below says why a slot's ink could not do that job.
+ */
+export const MODEL_BADGE = {
+	opus: {
+		/** label 4.88:1 on its bar */
+		light: { bg: "#D3E7EC", fg: "#0E5F73", bar: "#92CEDC", label: "#125463" },
+		/** label 4.93:1 on its bar */
+		dark: { bg: "#0E7C94", fg: "#F0FDFF", bar: "#48C8E0", label: "#044B58" },
+	},
+	sonnet: {
+		/** label 4.84:1 on its bar */
+		light: { bg: "#D6EEDD", fg: "#166534", bar: "#93D9B2", label: "#145D34" },
+		/** label 4.84:1 on its bar */
+		dark: { bg: "#12804F", fg: "#EFFFF6", bar: "#4FD98F", label: "#07572C" },
+	},
+	haiku: {
+		/** label 4.81:1 on its bar */
+		light: { bg: "#E6E6E0", fg: "#4B5563", bar: "#C9CCD2", label: "#4B5362" },
+		/** label 4.91:1 on its bar — the dark grey bar is the dimmest of the four, so
+		 *  its label is the closest to black of them. */
+		dark: { bg: "#697180", fg: "#F8FAFC", bar: "#8A92A2", label: "#21252E" },
+	},
+	fable: {
+		/** label 4.86:1 on its bar */
+		light: { bg: "#E9DCF5", fg: "#6B21A8", bar: "#C3A6EC", label: "#520FB0" },
+		/** label 4.81:1 on its bar */
+		dark: { bg: "#7B4CD6", fg: "#F6F0FF", bar: "#A87BE8", label: "#310570" },
+	},
+	/** Ochre. The first external slot, and the lightest step of the warm family.
+	 *  label 4.87:1 light / 4.81:1 dark, each on its own bar. */
+	mate1: {
+		light: { bg: "#F6E6C4", fg: "#7A5210", bar: "#E2C27A", label: "#654909" },
+		dark: { bg: "#926511", fg: "#FFF7E8", bar: "#D8A445", label: "#533807" },
+	},
+	/** Terracotta — the middle step, a clear ~17° of hue from either neighbour.
+	 *  label 4.80:1 light / 4.83:1 dark, each on its own bar. */
+	mate2: {
+		light: { bg: "#F7DDCB", fg: "#8A3E12", bar: "#EAB08A", label: "#793406" },
+		dark: { bg: "#A8501B", fg: "#FFF1E8", bar: "#E08A52", label: "#552404" },
+	},
+	/** Red earth. The third slot wears the reddest step, and it is still nowhere near
+	 *  `theme.colors.danger` — this is a desaturated earth tone, not a warning.
+	 *  label 4.86:1 light / 4.82:1 dark, each on its own bar. */
+	kangaroo: {
+		light: { bg: "#F6D6D0", fg: "#8E2F26", bar: "#E5A096", label: "#7B1C0E" },
+		dark: { bg: "#A83A2E", fg: "#FFEFEC", bar: "#E07A6C", label: "#571107" },
+	},
+	/**
+	 * THE FAMILY, not a fourth slot — the ink of the collapsed `mates` bar segment.
+	 *
+	 * A workflow bar draws every mate-routed agent as ONE run, because the question a bar
+	 * answers is "how much of this workflow leaves Claude Code" and that is one number. That
+	 * run cannot wear a slot's ink: painting a two-slot segment in `mate1`'s ochre says the
+	 * work went to `mate1`, and painting it in whichever slot contributes most makes the same
+	 * segment change colour when a count changes — the identical label in two hues down one
+	 * chart. So the family gets an ink of its own: honey amber, hue 35° light / 31° dark.
+	 *
+	 * It does NOT try to be a fourth distinguishable step, and it could not be. The warm band
+	 * is 0–50° and already holds three slots at ~17° spacing, so the widest gap left is about
+	 * 11° — under the separation the slots themselves needed. It does not have to be: the
+	 * family tone and the slot tones never appear in ONE graphic. The chart and the colour key
+	 * under it use only this; the tier table and the agent table use only the slots.
+	 *
+	 * MEASURED, same battery as the slots above:
+	 *   label on its own bar   light 4.97:1   dark 4.78:1
+	 *   fg on its own bg       light 5.87:1   dark 4.83:1
+	 *   dark bg vs grounds     4.03 (black) / 3.27 (#1C1C1E) / 2.69 (#282C34)   cream 4.88
+	 */
+	mates: {
+		light: { bg: "#F6E3C9", fg: "#80480F", bar: "#E5B77F", label: "#6B3D07" },
+		dark: { bg: "#9E5D16", fg: "#FFF5E8", bar: "#DB9A4C", label: "#553106" },
+	},
+	/** Not a model — the absence of a routing decision. Grey on both pages, so it never
+	 *  reads as another choice sitting beside the real ones. A mate is NOT this: a mate is
+	 *  a decision to route elsewhere, which is why it gets a colour and this does not.
+	 *
+	 *  Its label is a NEUTRAL grey at 4.82:1 light / 4.83:1 dark, and on the dark page it
+	 *  is the only label that is pale rather than deep — this is the one bar that is itself
+	 *  dark, so nothing darker could be read on it. */
+	inherit: {
+		light: { bg: "#EFEFE6", fg: "#8A8A80", bar: "#DEDED2", label: "#5E5E57" },
+		dark: { bg: "#4A4A54", fg: "#D0D2D8", bar: "#4E4E58", label: "#C6C6CA" },
+	},
+} as const;
+
+export type ModelBadgeKind = keyof typeof MODEL_BADGE;
+
+/**
+ * Fill, ink and page-text for the report's state badges — one set per page.
+ *
+ * Every value here is LIFTED from `MODEL_BADGE` above rather than invented, so
+ * the contrast measurements recorded there carry over. Ink on fill, and the
+ * page text on its own ground, both measured here:
+ *
+ *   update      `sonnet`    green      ink/fill 5.82 light, 4.80 dark
+ *                                      text 6.68 on cream, 9.44 on #1C1C1E
+ *   deprecated  `kangaroo`  red earth  label 4.86 light on its own bar
+ *   fix         `fable`     purple     label 4.86 light on its own bar
+ *
+ * `text` is the tone for a heading or glyph drawn ON THE PAGE, which is not the
+ * same question as ink on a fill: on cream it is the deep member of the family,
+ * on near-black the pale one. Using the fill for both put a mid-amber heading on
+ * a dark page, where it reads as dirt.
+ *
+ * Green, not ochre, because green is what an update wears elsewhere in magus
+ * and the report was the odd one out. It is a like-for-like swap inside the same
+ * measured system: the green fill separates from the page by 1.15 on cream and
+ * 3.42 on near-black, against the ochre's 1.15 and 3.32.
+ *
+ * Amber is NOT freed up by this — `unknown` still wears it, and that is the
+ * distinction worth keeping: green says "there is a newer version", amber says
+ * "we could not tell".
+ *
+ * Purple carries "fix required" because the warm band is spoken for and the
+ * measured set has no blue. Hue, not meaning — the badge says the word.
+ */
+const REPORT_BADGE = {
+	update: {
+		light: { fill: "#D6EEDD", ink: "#166534", text: "#166534" },
+		dark: { fill: "#12804F", ink: "#EFFFF6", text: "#4FD98F" },
+	},
+	deprecated: {
+		light: { fill: "#F6D6D0", ink: "#8E2F26", text: "#8E2F26" },
+		dark: { fill: "#A83A2E", ink: "#FFEFEC", text: "#E07A6C" },
+	},
+	fix: {
+		light: { fill: "#E9DCF5", ink: "#6B21A8", text: "#6B21A8" },
+		dark: { fill: "#7B4CD6", ink: "#F6F0FF", text: "#A87BE8" },
+	},
+} as const;
+
+export type ReportBadgeKind = keyof typeof REPORT_BADGE;
+
+export interface ReportInk {
+	/** The badge's fill. */
+	fill: string;
+	/** Ink for the word written on `fill`. */
+	ink: string;
+	/** The tone for a heading or glyph on the page itself. */
+	text: string;
+}
+
+/** Badge colours for one report state, for the resolved page. */
+export function reportBadge(kind: ReportBadgeKind): ReportInk {
+	return REPORT_BADGE[kind][detected];
+}
+
+/**
+ * The unfilled part of a bar — `░` — for the page this run resolved.
+ *
+ * A track is CHROME. It exists so the eye can see how long the bar could have
+ * been, and it must never compete with the fill. "Quiet" is only definable
+ * against a page, which is why this lives here and not beside the ramps.
+ *
+ * It was a single dark grey, `darken(brand.muted, 0.68)` = #222429, chosen
+ * against a near-black terminal and applied on both. MEASURED against the two
+ * reference grounds:
+ *
+ *              #222429 (was)     this table
+ *   dark       1.10:1  quiet     1.10:1  quiet
+ *   cream     14.54:1  LOUDEST   1.24:1  quiet
+ *
+ * 14.54:1 is higher contrast than the body text. On a light terminal the empty
+ * half of every step bar was the most prominent thing in the report — a dense
+ * stipple that read as hatched texture and buried a 1 ms step's actual fill.
+ * The light value steps from the page TOWARD `brand.muted` rather than scaling
+ * a grey, so it stays in the page's own hue instead of laying cold grey on warm
+ * cream.
+ */
+const BAR_TRACK = { light: "#E0E2C3", dark: "#222429" } as const;
+
+export function barTrack(): string {
+	return BAR_TRACK[detected];
+}
+
+export interface ModelInk {
+	bg: string;
+	fg: string;
+	bar: string;
+	/** Ink for a word written ON `bar`. Never `fg` — see the note above `MODEL_BADGE`. */
+	label: string;
+}
+
+/**
+ * Chip and bar colours for one model, for the resolved mode.
+ *
+ * Total by construction: a name this build does not know gets `inherit`'s grey, which reads
+ * as "magus does not recognise this" rather than as a missing colour. A hand-edited
+ * config can name anything.
+ */
+export function modelBadge(kind: string): ModelInk {
+	const key = (kind in MODEL_BADGE ? kind : "inherit") as ModelBadgeKind;
+	return MODEL_BADGE[key][detected];
+}
+
+/**
+ * The UNLIT track: the `·` behind an effort dot, the `░` behind a bar.
+ *
+ * Light reuses `SCOPE_OFF_FILL`, which already solves this there. Dark does NOT: at
+ * `#3A3A40` the track measures 1.51:1 on the reference page and simply vanishes, so a bar
+ * reads as a floating block with no scale and the effort dots lose the denominator that
+ * makes them a level rather than a count. `#4A4A52` is 1.94:1 — still recessive, still
+ * visible.
+ */
+export const TRACK_FILL = {
+	light: SCOPE_OFF_FILL.light,
+	dark: "#4A4A52",
+} as const;
+
+/** Fill for an unlit track segment, for the resolved mode. */
+export function trackFill(): string {
+	return TRACK_FILL[detected];
+}
+
+/**
+ * Effort's colour ramp — TEXT only, never a fill, so a row never paints two blocks.
+ *
+ * Effort is an ORDINAL, so these are a ramp rather than four unrelated hues. The ramp avoids
+ * green and red, which already mean "on" and "failed" elsewhere on the same screen: one
+ * colour, one meaning, app-wide. Dark runs brighter than light for the reason `MODEL_BADGE`
+ * gives — a dim colour on a dark page is a grey one.
+ */
+export const EFFORT_INK = {
+	low: { light: "#6B7280", dark: "#9AA0AC" },
+	medium: { light: "#0E7490", dark: "#6FD9F0" },
+	high: { light: "#B45309", dark: "#F2B25E" },
+	xhigh: { light: "#A21CAF", dark: "#E49BFF" },
+} as const;
+
+export type EffortInkKind = keyof typeof EFFORT_INK;
+
+/** Ink for one effort level, for the resolved mode. Unknown words take the lowest step. */
+export function effortInk(effort: string): string {
+	const key = (effort in EFFORT_INK ? effort : "low") as EffortInkKind;
+	return EFFORT_INK[key][detected];
+}
+
+/**
+ * The two reference pages, mirrored from `theme.ts`'s `CONTRAST_REFERENCE`.
+ *
+ * Duplicated deliberately: `theme.ts` imports opentui's RGBA, which drags the
+ * renderer into anything that touches it. This module is pure data by design so
+ * the colour tests can run without a terminal. A test asserts the two agree.
+ */
+export const CONTRAST_REFERENCE_KEYS = {
+	light: "#FAFAD2",
+	dark: "#1C1C1E",
+} as const;
+
+/** Chip colours for one component kind, for the resolved mode. */
+export function componentBadge(kind: ComponentBadgeKind): {
+	bg: string;
+	fg: string;
+} {
+	return COMPONENT_BADGE[kind][detected];
+}

package/src/ui/theme-resolve.ts

@@ -0,0 +1,147 @@
+import type { ThemeMode } from "@opentui/core";
+
+/**
+ * Terminal theme resolution — the one order magus follows, decided once at
+ * process start, first answer wins:
+ *
+ *   1. `--theme` flag
+ *   2. `MAGUS_THEME`
+ *   3. `TERM_THEME`
+ *   4. OSC 10/11 probe (bounded, interactive tty only)
+ *   5. `COLORFGBG`
+ *   6. dark
+ *
+ * A step with no answer says nothing and the next one runs; nothing before
+ * step 6 ever asserts dark. Every theme word is compared exactly — the byte
+ * strings `light` and `dark`, lowercase, untrimmed — because the same test has
+ * to run in a POSIX `case` and a tmux format, and only the exact comparison is
+ * free in all three.
+ *
+ * This module is pure by design: no `process` access except as a *default
+ * argument* to `snapshotThemeEnv`, no I/O, no renderer. Everything it needs is
+ * passed in, so the whole contract runs in a test without a terminal.
+ */
+
+export type ThemeSource =
+	| "flag"
+	| "variable"
+	| "TERM_THEME"
+	| "osc11"
+	| "COLORFGBG"
+	| "default";
+
+export interface ThemeResolution {
+	/** Never null — when nothing answered, it is dark by decision. */
+	mode: ThemeMode;
+	source: ThemeSource;
+}
+
+/** The three variables the resolver reads, captured BEFORE .env is merged. */
+export interface ThemeEnv {
+	TERM_THEME?: string;
+	MAGUS_THEME?: string;
+	COLORFGBG?: string;
+}
+
+export interface ResolveThemeInput {
+	/** Already validated by the router: only "light" | "dark" | undefined arrive here. */
+	flag?: ThemeMode;
+	env: ThemeEnv;
+	/** stdin AND stdout are TTYs. Decided by the caller; the resolver never touches process. */
+	isInteractive: boolean;
+	/** Bounded OSC 10/11 probe. Called at most once, and only when step 4 is reached. */
+	probe: () => Promise<ThemeMode | null>;
+}
+
+/** Exact match on "light" | "dark"; everything else is no opinion. */
+export function parseThemeWord(value: string | undefined): ThemeMode | null {
+	if (value === "light") return "light";
+	if (value === "dark") return "dark";
+	return null;
+}
+
+/** The literal background fields that answer — the same set as the statusline's `case`. */
+const LIGHT_BACKGROUNDS: ReadonlySet<string> = new Set(["7", "15"]);
+const DARK_BACKGROUNDS: ReadonlySet<string> = new Set([
+	"0",
+	"1",
+	"2",
+	"3",
+	"4",
+	"5",
+	"6",
+	"8",
+	"9",
+	"10",
+	"11",
+	"12",
+	"13",
+	"14",
+]);
+
+/**
+ * Last ";"-field is the background: 7|15 → light, 0-6|8-14 → dark, else null.
+ *
+ * Exact string membership, not numeric parsing: the statusline's
+ * `parse_colorfgbg` is a POSIX `case` over the literal words, so `07`, `015`
+ * and `00` are no opinion there, and that literal set is the contract the two
+ * tools share. `Number("07")` would make magus say light where the
+ * statusline says nothing.
+ *
+ * A value without a `;` is not `<fg>;<bg>` at all — a lone `7` is no opinion,
+ * matching the statusline's `case "$1" in *\;*)` guard so the two tools agree.
+ */
+export function parseColorFgBg(value: string | undefined): ThemeMode | null {
+	if (value === undefined || !value.includes(";")) return null;
+	const bg = value.slice(value.lastIndexOf(";") + 1);
+	if (LIGHT_BACKGROUNDS.has(bg)) return "light";
+	if (DARK_BACKGROUNDS.has(bg)) return "dark";
+	return null;
+}
+
+/**
+ * Copy the three variables out of `env` — call this before loadProjectDotenv.
+ *
+ * Copies, never references: the returned object must not observe later writes
+ * to `process.env`, which is exactly what a merged `.env` would be.
+ */
+export function snapshotThemeEnv(
+	env: Readonly<Record<string, string | undefined>> = process.env,
+): ThemeEnv {
+	const snapshot: ThemeEnv = {};
+	if (env.TERM_THEME !== undefined) snapshot.TERM_THEME = env.TERM_THEME;
+	if (env.MAGUS_THEME !== undefined) snapshot.MAGUS_THEME = env.MAGUS_THEME;
+	if (env.COLORFGBG !== undefined) snapshot.COLORFGBG = env.COLORFGBG;
+	return snapshot;
+}
+
+export async function resolveTheme(
+	input: ResolveThemeInput,
+): Promise<ThemeResolution> {
+	if (input.flag !== undefined) {
+		return { mode: input.flag, source: "flag" };
+	}
+
+	const variable = parseThemeWord(input.env.MAGUS_THEME);
+	if (variable !== null) return { mode: variable, source: "variable" };
+
+	const termTheme = parseThemeWord(input.env.TERM_THEME);
+	if (termTheme !== null) return { mode: termTheme, source: "TERM_THEME" };
+
+	// Steps 1-3 answered nothing, so this is the only path that probes. Not
+	// reaching here is what keeps first paint undelayed when a word answered.
+	if (input.isInteractive) {
+		let probed: ThemeMode | null = null;
+		try {
+			probed = await input.probe();
+		} catch {
+			probed = null;
+		}
+		if (probed !== null) return { mode: probed, source: "osc11" };
+	}
+
+	const colorFgBg = parseColorFgBg(input.env.COLORFGBG);
+	if (colorFgBg !== null) return { mode: colorFgBg, source: "COLORFGBG" };
+
+	return { mode: "dark", source: "default" };
+}