From b91d5ef5a34031104276d999baaaa8511694a58d Mon Sep 17 00:00:00 2001
From: Ayman Bagabas <ayman.bagabas@gmail.com>
Date: Tue, 4 Aug 2026 15:06:29 -0400
Subject: [PATCH] feat(terminal): answer OSC color queries and track dynamic
 colors
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Programs ask the terminal what color it is before deciding whether to
draw for a light or a dark background. Nothing answered, so every one of
them blocked until it timed out and guessed.

The emulator answers now, through `take_pending_writes`, which already
exists for exactly this: the replies a terminal owes to device queries.
alacritty parses the sequence, tracks what a program set, and hands back
a formatter with the query's own prefix and terminator already captured,
so the only missing piece was the color itself. That comes from the
session profile, which the emulator is now constructed with.

The alternative was parsing the sequences off the PTY stream, the way
shell integration is tracked. That would have meant reimplementing color
parsing, the runtime table, reply formatting, and terminator tracking,
all of which the emulator already does — and getting the terminator
wrong, since it is only visible to whoever parsed the sequence. Reading
what the emulator already knows is both less code and more faithful.

Colors resolve in three layers: what a program set, else the session
profile, else the table the specification defines. A reset clears only
the first, so the profile is unreachable from the byte stream and there
is always something to restore. That is what the specification asks for,
describing a reset as restoring "the color specified by the corresponding
X resource".

`Emulator` gains `color(slot)`, which every backend answers from its own
state, plus a `palette()` snapshot of all 259 slots. The screenshot
renderer and `expect --fg/--bg` take that snapshot rather than the
emulator, so neither holds the session lock while it renders, and neither
knows which backend produced the colors.

Five conformance cases cover queries, terminator echo, set-then-reset,
unconfigured indices, and that a cell follows whatever its slot now
holds. They run against every backend, so a future one cannot answer
differently. An end-to-end test drives a real program through the whole
path: it reads the configured background, sets its own, resets, and gets
the configured one back.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: Ayman Bagabas <ayman.bagabas@gmail.com>

Rebasing onto a main that had since gained window titles folded the
follow-up commits into this one, so it also carries: color resolution
moved into the emulator so a screenshot and an assertion both see what a
program set, `ColorSlot` naming the three dynamic colors instead of
numbering them, snapshot coverage pinning that a snapshot records the
slot rather than the color it resolves to, and the fix that answers
queries in the order they were asked rather than appending every color
reply last.
---
 SKILL.md                                      |   6 +
 crates/shell-use-cli/src/monitor.rs           |   2 +-
 .../shell-use-cli/tests/session_lifecycle.rs  | 105 ++++++
 crates/shell-use/src/assert/color.rs          |  82 ++++-
 crates/shell-use/src/assert/snapshot.rs       |  37 +++
 crates/shell-use/src/engine.rs                |  24 +-
 crates/shell-use/src/profile.rs               | 154 ++++++---
 crates/shell-use/src/render/svg.rs            | 114 +++++--
 crates/shell-use/src/session.rs               |   5 +-
 crates/shell-use/src/terminal/alacritty.rs    | 211 ++++++++++--
 crates/shell-use/src/terminal/conformance.rs  | 303 +++++++++++++++++-
 crates/shell-use/src/terminal/emu.rs          |  37 ++-
 12 files changed, 961 insertions(+), 119 deletions(-)

diff --git a/SKILL.md b/SKILL.md
index b24390a..07a7d69 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -327,6 +327,12 @@ stable across profiles.
 The palette is what a screenshot paints **and** what `expect --fg/--bg` matches
 a `#rrggbb` against, so the two always agree.
 
+Programs can also set and query colours at runtime with `OSC 4/10/11/12` and
+reset them with `OSC 104/110/111/112`. A query is answered with the colour
+currently showing; a reset restores the profile's colour, which no escape
+sequence can change. Note that a program setting a colour also changes what a
+screenshot of that session looks like.
+
 ## Supported shells & integration
 
 `open --shell S` accepts: `bash`, `zsh`, `fish`, `powershell`, `pwsh`, `cmd`,
diff --git a/crates/shell-use-cli/src/monitor.rs b/crates/shell-use-cli/src/monitor.rs
index c2e2eb9..729ba34 100644
--- a/crates/shell-use-cli/src/monitor.rs
+++ b/crates/shell-use-cli/src/monitor.rs
@@ -395,7 +395,7 @@ mod tests {
         ];
 
         for want in styles {
-            let mut emu = AlacrittyEmu::new(10, 2, 0);
+            let mut emu = AlacrittyEmu::new(10, 2, &shell_use::profile::Profile::default());
             emu.process(want.sgr().as_bytes());
             emu.process(b"x");
             let got = Style::from(&emu.viewable_rows()[0][0]);
diff --git a/crates/shell-use-cli/tests/session_lifecycle.rs b/crates/shell-use-cli/tests/session_lifecycle.rs
index fb18594..4d0eb69 100644
--- a/crates/shell-use-cli/tests/session_lifecycle.rs
+++ b/crates/shell-use-cli/tests/session_lifecycle.rs
@@ -343,6 +343,111 @@ fn an_unknown_profile_is_rejected() {
     );
 }
 
+/// A program that asks the terminal what color it is gets an answer.
+///
+/// This is how tools decide whether they are on a light or a dark background.
+/// A terminal that stays silent leaves them blocked until they time out and
+/// guess, so this drives the whole path: daemon, emulator, and the reply on
+/// its way back up the PTY.
+///
+/// Unix only, because the probe has to put its own terminal in raw mode to
+/// read a reply that arrives without a newline and must not be echoed, and
+/// `termios` does not exist on Windows CPython. The reply itself is not
+/// platform specific: how it is formatted is covered by conformance cases
+/// that run against every backend, and the write that carries it to the child
+/// is the same `pty.write` every `type` and `submit` on Windows already uses.
+#[cfg(unix)]
+#[test]
+fn a_color_query_is_answered_over_the_pty() {
+    let sandbox = Sandbox::new("osc-query");
+    let probe = sandbox.home.join("probe.py");
+    std::fs::write(
+        &probe,
+        r#"
+import os, sys, termios, tty, select
+
+# Unbuffered reads: a buffered reader would take bytes off the fd that
+# select() then cannot see, and the reply would look truncated.
+def ask(fd, query):
+    os.write(1, query)
+    buf = b""
+    while select.select([fd], [], [], 2.0)[0]:
+        buf += os.read(fd, 64)
+        if buf.endswith(b"\x07"):
+            break
+    return buf.decode("utf8", "replace")
+
+fd = sys.stdin.fileno()
+old = termios.tcgetattr(fd)
+try:
+    tty.setraw(fd)
+    configured = ask(fd, b"\x1b]11;?\x07")
+    # Every dynamic colour, not just the background: a program that sets the
+    # foreground and cursor has to be answered about those too.
+    os.write(1, b"\x1b]10;#abcdef\x07\x1b]11;#654321\x07\x1b]12;#fedcba\x07")
+    fg = ask(fd, b"\x1b]10;?\x07")
+    overridden = ask(fd, b"\x1b]11;?\x07")
+    cursor = ask(fd, b"\x1b]12;?\x07")
+    os.write(1, b"\x1b]111\x07")
+    restored = ask(fd, b"\x1b]11;?\x07")
+finally:
+    termios.tcsetattr(fd, termios.TCSADRAIN, old)
+
+strip = lambda s: s.replace("\x1b", "").replace("\x07", "")
+print("\r\nRESULT %s %s %s %s %s\r" % (
+    strip(configured), strip(fg), strip(overridden), strip(cursor), strip(restored)))
+"#,
+    )
+    .expect("write probe");
+
+    // Wide enough that the report is one unwrapped line: `text` returns the
+    // grid, so a wrapped reply would be split across rows.
+    sandbox.ok(&["run", "--cols", "200", "--", "bash", "--norc"]);
+    sandbox.ok(&[
+        "submit",
+        &format!("python3 {}", probe.to_str().expect("utf-8 path")),
+    ]);
+    // Wait for the line this test reads, not for the command.
+    //
+    // The probe prints nothing until it is done: its queries go to the
+    // terminal, which answers them rather than echoing them, so the screen
+    // stays unchanged for as long as python takes to start. `bash --norc` has
+    // no shell integration, so `wait command` falls back to "the prompt came
+    // back and the screen is idle", and on a loaded machine an idle screen
+    // arrives long before the report does.
+    sandbox.ok(&["wait", "text", "RESULT", "--timeout", "30000"]);
+    let text = sandbox.ok(&["text", "--full"]);
+
+    let line = text
+        .lines()
+        .find(|l| l.contains("RESULT"))
+        .unwrap_or_else(|| panic!("the probe never reported: {text}"));
+
+    // The default profile's background is black, so the terminal reports it,
+    // then the color the program set, then the configured one again.
+    assert!(
+        line.contains("]11;rgb:0000/0000/0000"),
+        "the configured background should be reported: {line}"
+    );
+    assert!(
+        line.contains("]11;rgb:6565/4343/2121"),
+        "a set background should be reported back: {line}"
+    );
+    assert!(
+        line.contains("]10;rgb:abab/cdcd/efef"),
+        "a set foreground should be reported back: {line}"
+    );
+    assert!(
+        line.contains("]12;rgb:fefe/dcdc/baba"),
+        "a set cursor color should be reported back: {line}"
+    );
+    assert_eq!(
+        line.matches("]11;rgb:0000/0000/0000").count(),
+        2,
+        "a reset should restore the configured background: {line}"
+    );
+}
+
 #[test]
 fn state_reports_effective_timeouts() {
     let sandbox = Sandbox::new("state-timeouts");
diff --git a/crates/shell-use/src/assert/color.rs b/crates/shell-use/src/assert/color.rs
index 56105ef..ed6b245 100644
--- a/crates/shell-use/src/assert/color.rs
+++ b/crates/shell-use/src/assert/color.rs
@@ -1,7 +1,7 @@
 //! Color parsing and comparison for `expect --fg/--bg`.
 
 use super::super::terminal::cell::Color;
-use crate::profile::Colors;
+use crate::terminal::emu::Emulator;
 
 /// The spelling of [`Expected::Default`], on the command line and in messages.
 pub const DEFAULT: &str = "default";
@@ -74,7 +74,7 @@ fn parse_hex(hex: &str) -> anyhow::Result<(u8, u8, u8)> {
 /// the screenshot renderer draws with. These used to be two separate hardcoded
 /// tables that disagreed on every ANSI slot, so `expect --fg "#800000"` passed
 /// on a cell a screenshot painted `#e88388`.
-pub fn matches(cell: Option<Color>, expected: &Expected, colors: &Colors) -> bool {
+pub fn matches(cell: Option<Color>, expected: &Expected, colors: &dyn Emulator) -> bool {
     let Some(cell) = cell else {
         return matches!(expected, Expected::Default);
     };
@@ -89,7 +89,7 @@ pub fn matches(cell: Option<Color>, expected: &Expected, colors: &Colors) -> boo
 }
 
 /// Render a cell's color in the same space as the expected value, for messages.
-pub fn describe_cell(cell: Option<Color>, expected: &Expected, colors: &Colors) -> String {
+pub fn describe_cell(cell: Option<Color>, expected: &Expected, colors: &dyn Emulator) -> String {
     let Some(cell) = cell else {
         return DEFAULT.to_string();
     };
@@ -124,7 +124,23 @@ pub fn rgb_to_ansi256(r: u8, g: u8, b: u8) -> u8 {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use crate::profile::{Colors, Profile};
+    use crate::terminal::alacritty::AlacrittyEmu;
     use crate::terminal::cell::Color;
+    use crate::terminal::emu::Emulator;
+
+    /// A real emulator, so these exercise the same resolution path a session
+    /// uses rather than a stand-in that could drift from it.
+    fn emu_with(colors: Colors) -> AlacrittyEmu {
+        AlacrittyEmu::new(
+            10,
+            2,
+            &Profile {
+                colors,
+                ..Default::default()
+            },
+        )
+    }
 
     #[test]
     fn parse_forms() {
@@ -144,7 +160,7 @@ mod tests {
 
     #[test]
     fn matches_palette_and_default() {
-        let c = Colors::default();
+        let c = emu_with(Colors::default());
         let idx = |i| Some(Color::from_index(i));
         assert!(matches(idx(9), &Expected::Ansi256(9), &c));
         assert!(!matches(idx(2), &Expected::Ansi256(9), &c));
@@ -161,7 +177,7 @@ mod tests {
     /// `default` keyword, which is the way to assert on it.
     #[test]
     fn default_color_matches_only_default() {
-        let c = Colors::default();
+        let c = emu_with(Colors::default());
         assert!(!matches(None, &Expected::Ansi256(0), &c));
         assert!(!matches(None, &Expected::Hex(0, 0, 0), &c));
         assert!(matches(None, &Expected::Default, &c));
@@ -170,7 +186,7 @@ mod tests {
 
     #[test]
     fn a_colored_cell_is_not_default() {
-        let c = Colors::default();
+        let c = emu_with(Colors::default());
         let red = Some(Color::from_index(1));
         assert!(!matches(red, &Expected::Default, &c));
         assert!(matches(red, &Expected::Ansi256(1), &c));
@@ -190,7 +206,7 @@ mod tests {
     /// value for every slot, because both come from the profile.
     #[test]
     fn an_assertion_matches_the_color_a_screenshot_paints() {
-        let colors = Colors::default();
+        let colors = emu_with(Colors::default());
         for index in 0u8..=255 {
             let cell = Some(Color::from_index(index));
             let painted = colors.resolve(cell, true);
@@ -206,14 +222,62 @@ mod tests {
         }
     }
 
+    /// An assertion compares against what the terminal is *currently*
+    /// showing, so a program that recolors a slot changes what matches.
+    ///
+    /// This is the other half of the screenshot test: both read the same
+    /// state, so a colour a screenshot paints is a colour an assertion
+    /// matches, at every point in a session rather than only at the start.
+    #[test]
+    fn an_assertion_follows_a_color_a_program_set() {
+        use crate::terminal::emu::Emulator;
+        let mut emu = emu_with(Colors::default());
+        let red = Some(Color::from_index(1));
+        let configured = Colors::default().red;
+
+        assert!(matches(
+            red,
+            &Expected::Hex(configured.r, configured.g, configured.b),
+            &emu
+        ));
+
+        emu.process(b"\x1b]4;1;#22c55e\x07");
+        assert!(
+            matches(red, &Expected::Hex(0x22, 0xc5, 0x5e), &emu),
+            "the assertion follows the colour the program set"
+        );
+        assert!(
+            !matches(
+                red,
+                &Expected::Hex(configured.r, configured.g, configured.b),
+                &emu
+            ),
+            "the configured colour is no longer what slot 1 shows"
+        );
+        assert!(
+            matches(red, &Expected::Ansi256(1), &emu),
+            "the index is unaffected: it names a slot, not a colour"
+        );
+
+        emu.process(b"\x1b]104;1\x07");
+        assert!(
+            matches(
+                red,
+                &Expected::Hex(configured.r, configured.g, configured.b),
+                &emu
+            ),
+            "a reset restores the configured colour"
+        );
+    }
+
     /// A profile's palette is what an assertion compares against, so two
     /// profiles genuinely disagree rather than sharing one hardcoded table.
     #[test]
     fn a_recolored_profile_moves_what_an_assertion_matches() {
-        let colors = Colors {
+        let colors = emu_with(Colors {
             red: crate::profile::Rgb::new(1, 2, 3),
             ..Default::default()
-        };
+        });
         let red = Some(Color::from_index(1));
         assert!(matches(red, &Expected::Hex(1, 2, 3), &colors));
         assert!(!matches(red, &Expected::Hex(128, 0, 0), &colors));
diff --git a/crates/shell-use/src/assert/snapshot.rs b/crates/shell-use/src/assert/snapshot.rs
index 2707033..df3b6a6 100644
--- a/crates/shell-use/src/assert/snapshot.rs
+++ b/crates/shell-use/src/assert/snapshot.rs
@@ -199,6 +199,43 @@ mod tests {
         }
     }
 
+    /// A snapshot records the palette *slot* a cell chose, never the color
+    /// that slot resolves to.
+    ///
+    /// This is what lets a saved baseline outlive a profile change: the same
+    /// screen recorded under two profiles that disagree about what red looks
+    /// like still produces the same snapshot, so recoloring a terminal does
+    /// not invalidate every snapshot in a suite.
+    #[test]
+    fn a_snapshot_records_the_slot_rather_than_the_color() {
+        let colored = EmuCell {
+            ch: "x".into(),
+            fg: Some(Color::from_index(1)),
+            ..EmuCell::blank()
+        };
+        let out = serialize(&[vec![colored]], 1, true, None);
+        assert!(
+            out.contains("\"fg\": 1"),
+            "the slot is recorded, not an rgb value: {out}"
+        );
+        assert!(
+            !out.contains('#'),
+            "a palette color must not be resolved into the snapshot: {out}"
+        );
+    }
+
+    /// A true-color cell names its own color, so that one *is* recorded
+    /// literally: no profile can change what `38;2;r;g;b` means.
+    #[test]
+    fn a_true_color_cell_records_its_own_value() {
+        let rgb = EmuCell {
+            ch: "x".into(),
+            fg: Some(Color::Rgb(0x11, 0x22, 0x33)),
+            ..EmuCell::blank()
+        };
+        assert!(serialize(&[vec![rgb]], 1, true, None).contains("#112233"));
+    }
+
     fn cell(s: &str) -> EmuCell {
         EmuCell {
             ch: s.into(),
diff --git a/crates/shell-use/src/engine.rs b/crates/shell-use/src/engine.rs
index a51a28c..8d08b90 100644
--- a/crates/shell-use/src/engine.rs
+++ b/crates/shell-use/src/engine.rs
@@ -1176,9 +1176,18 @@ fn expect_text(
         || {
             matched = match locator::find(&grid(session, full), &pattern, strict) {
                 Ok(Some(cells)) if !cells.is_empty() => {
-                    if let Some(error) =
-                        check_colors(&cells, &fg, &bg, not, &session.profile.colors)
-                    {
+                    if let Some(error) = check_colors(
+                        &cells,
+                        &fg,
+                        &bg,
+                        not,
+                        session
+                            .state
+                            .lock()
+                            .unwrap_or_else(std::sync::PoisonError::into_inner)
+                            .emu
+                            .as_ref(),
+                    ) {
                         last_error = Some(error);
                         false
                     } else {
@@ -1219,7 +1228,7 @@ fn check_colors(
     fg: &Option<String>,
     bg: &Option<String>,
     not: bool,
-    colors: &crate::profile::Colors,
+    colors: &dyn crate::terminal::emu::Emulator,
 ) -> Option<String> {
     let want = !not;
     if let Some(spec) = fg {
@@ -1353,7 +1362,12 @@ fn screenshot(
             let svg = crate::render::svg::render_svg(
                 &rows,
                 session.cols,
-                &session.profile.colors,
+                session
+                    .state
+                    .lock()
+                    .unwrap_or_else(std::sync::PoisonError::into_inner)
+                    .emu
+                    .as_ref(),
                 title.as_deref(),
             );
             std::fs::write(&path, svg)
diff --git a/crates/shell-use/src/profile.rs b/crates/shell-use/src/profile.rs
index ec98799..698afd7 100644
--- a/crates/shell-use/src/profile.rs
+++ b/crates/shell-use/src/profile.rs
@@ -22,7 +22,7 @@ use std::path::{Path, PathBuf};
 
 use serde::{Deserialize, Deserializer, Serialize, Serializer};
 
-use crate::terminal::cell::{Color, NamedColor};
+use crate::terminal::cell::NamedColor;
 
 /// Rows of scrollback a profile retains when it does not say otherwise.
 ///
@@ -193,47 +193,85 @@ impl Colors {
 
     /// Resolve any 256-color index.
     ///
-    /// Slots 0-15 come from the profile. The color cube (16-231) and gray ramp
-    /// (232-255) are fixed by the xterm spec and identical under every profile.
+    /// Slots 0-15 come from the profile; everything above comes from the
+    /// xterm table, which no profile can move.
     pub fn rgb(&self, index: u8) -> Rgb {
         match index {
             0..=15 => self.ansi()[index as usize],
-            16..=231 => {
-                let i = index as u16 - 16;
-                let level = |c: u16| -> u8 {
-                    if c == 0 {
-                        0
-                    } else {
-                        (c * 40 + 55) as u8
-                    }
-                };
-                Rgb::new(level((i / 36) % 6), level((i / 6) % 6), level(i % 6))
-            }
-            232..=255 => {
-                let v = ((index as u16 - 232) * 10 + 8) as u8;
-                Rgb::new(v, v, v)
-            }
+            _ => xterm_color(index),
         }
     }
+}
 
-    /// Resolve a cell's color, where `None` is the terminal default.
-    ///
-    /// This is the one function both the screenshot renderer and `expect
-    /// --fg/--bg` call, which is what keeps them agreeing.
-    pub fn resolve(&self, color: Option<Color>, is_fg: bool) -> Rgb {
-        match color {
-            None => {
-                if is_fg {
-                    self.foreground
-                } else {
-                    self.background
-                }
-            }
-            Some(Color::Named(n)) => self.rgb(n.index()),
-            Some(Color::Idx(i)) => self.rgb(i),
-            Some(Color::Rgb(r, g, b)) => Rgb::new(r, g, b),
-        }
+/// A color a program can address.
+///
+/// `OSC 4` names a palette entry and `OSC 10/11/12` name the three defaults.
+/// Emulators number these however they like internally, so each backend
+/// translates its own layout and that numbering never reaches here.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ColorSlot {
+    Indexed(u8),
+    Foreground,
+    Background,
+    Cursor,
+}
+
+/// The xterm 256-color table, which is the same in every terminal.
+///
+/// Slots 0-15 here are the classic VGA colors, and a profile overrides them.
+/// The rest is the 6x6x6 color cube and the 24-step gray ramp, which the
+/// specification fixes and no profile can move: `--fg 196` has to mean the
+/// same thing in every session.
+static XTERM_256: [Rgb; 256] = build_xterm_256();
+
+const fn build_xterm_256() -> [Rgb; 256] {
+    let mut table = [Rgb::new(0, 0, 0); 256];
+
+    // 0-15: VGA.
+    let vga = [
+        (0, 0, 0),
+        (128, 0, 0),
+        (0, 128, 0),
+        (128, 128, 0),
+        (0, 0, 128),
+        (128, 0, 128),
+        (0, 128, 128),
+        (192, 192, 192),
+        (128, 128, 128),
+        (255, 0, 0),
+        (0, 255, 0),
+        (255, 255, 0),
+        (0, 0, 255),
+        (255, 0, 255),
+        (0, 255, 255),
+        (255, 255, 255),
+    ];
+    let mut i = 0;
+    while i < 16 {
+        table[i] = Rgb::new(vga[i].0, vga[i].1, vga[i].2);
+        i += 1;
+    }
+
+    // 16-231: a 6x6x6 cube whose levels step 0, 95, 135, 175, 215, 255.
+    let levels = [0u8, 95, 135, 175, 215, 255];
+    while i < 232 {
+        let n = i - 16;
+        table[i] = Rgb::new(levels[(n / 36) % 6], levels[(n / 6) % 6], levels[n % 6]);
+        i += 1;
     }
+
+    // 232-255: a gray ramp from 8 to 238 in steps of 10.
+    while i < 256 {
+        let v = (i - 232) as u8 * 10 + 8;
+        table[i] = Rgb::new(v, v, v);
+        i += 1;
+    }
+    table
+}
+
+/// The color a slot has when nothing has overridden it.
+pub fn xterm_color(index: u8) -> Rgb {
+    XTERM_256[index as usize]
 }
 
 /// The settings a session runs with.
@@ -448,15 +486,47 @@ mod tests {
         assert_eq!(Colors::slot_name(16), None, "only 0-15 are configurable");
     }
 
+    /// The 16 configurable slots come from the profile; the rest come from the
+    /// xterm table, which is the same in every terminal.
     #[test]
-    fn a_cell_that_set_no_color_takes_the_profile_default() {
-        let c = Colors::default();
-        assert_eq!(c.resolve(None, true), c.foreground);
-        assert_eq!(c.resolve(None, false), c.background);
+    fn only_the_ansi_slots_follow_the_profile() {
+        let recolored = Colors {
+            red: Rgb::new(1, 2, 3),
+            ..Default::default()
+        };
+        assert_eq!(recolored.rgb(1), Rgb::new(1, 2, 3), "slot 1 follows it");
+        for index in 16u8..=255 {
+            assert_eq!(
+                recolored.rgb(index),
+                xterm_color(index),
+                "slot {index} is fixed by the specification"
+            );
+        }
+    }
+
+    /// Spot-check the static table against the values the specification
+    /// defines, so a typo in 256 entries cannot pass unnoticed.
+    #[test]
+    fn the_xterm_table_matches_the_specification() {
+        assert_eq!(xterm_color(0), Rgb::new(0, 0, 0), "VGA black");
+        assert_eq!(xterm_color(1), Rgb::new(128, 0, 0), "VGA red");
+        assert_eq!(xterm_color(15), Rgb::new(255, 255, 255), "VGA bright white");
+        assert_eq!(
+            xterm_color(16),
+            Rgb::new(0, 0, 0),
+            "the cube starts at black"
+        );
+        assert_eq!(xterm_color(196), Rgb::new(255, 0, 0), "cube red");
+        assert_eq!(
+            xterm_color(231),
+            Rgb::new(255, 255, 255),
+            "the cube ends white"
+        );
+        assert_eq!(xterm_color(232), Rgb::new(8, 8, 8), "the ramp starts at 8");
         assert_eq!(
-            c.resolve(Some(Color::Rgb(1, 2, 3)), true),
-            Rgb::new(1, 2, 3),
-            "a true-color cell is itself whatever the profile says"
+            xterm_color(255),
+            Rgb::new(238, 238, 238),
+            "the ramp ends at 238"
         );
     }
 
diff --git a/crates/shell-use/src/render/svg.rs b/crates/shell-use/src/render/svg.rs
index e10b222..a86c509 100644
--- a/crates/shell-use/src/render/svg.rs
+++ b/crates/shell-use/src/render/svg.rs
@@ -11,8 +11,9 @@
 use std::fmt::Write;
 
 use super::nerd_font::NerdFont;
-use crate::profile::{Colors, Rgb};
+use crate::profile::{ColorSlot, Rgb};
 use crate::terminal::cell::{truncate_to_columns, Attrs, EmuCell};
+use crate::terminal::emu::Emulator;
 
 const CELL_W: f32 = 10.0;
 const CELL_H: f32 = 21.0;
@@ -47,7 +48,7 @@ fn cell_at(row: &[EmuCell], x: usize) -> &EmuCell {
 }
 
 /// Resolved background color for a cell (honoring inverse).
-fn bg_of(cell: &EmuCell, colors: &Colors) -> Rgb {
+fn bg_of(cell: &EmuCell, colors: &dyn Emulator) -> Rgb {
     let bg = colors.resolve(cell.bg, false);
     let fg = colors.resolve(cell.fg, true);
     if cell.has(Attrs::INVERSE) {
@@ -67,7 +68,7 @@ struct Style {
     invisible: bool,
 }
 
-fn style_of(cell: &EmuCell, colors: &Colors) -> Style {
+fn style_of(cell: &EmuCell, colors: &dyn Emulator) -> Style {
     let mut fg = colors.resolve(cell.fg, true);
     let bg = colors.resolve(cell.bg, false);
     if cell.has(Attrs::INVERSE) {
@@ -114,7 +115,7 @@ fn run_text(row: &[EmuCell], start: usize, end: usize) -> String {
 /// computed width would distort it. It is instead truncated to what fits, and
 /// kept clear of the traffic lights by reserving the same margin on both
 /// sides, which also keeps it centred on the space that remains.
-fn write_title(out: &mut String, title: &str, width: f32, colors: &Colors) {
+fn write_title(out: &mut String, title: &str, width: f32, colors: &dyn Emulator) {
     const GAP: f32 = 8.0;
     let available = width - 2.0 * (DOTS_RIGHT + GAP);
     // A monospace advance, scaled from the grid font's known cell width.
@@ -136,7 +137,7 @@ fn write_title(out: &mut String, title: &str, width: f32, colors: &Colors) {
         baseline = HEADER_H / 2.0 + TITLE_FONT_SIZE * 0.35,
         // The dim grey of the palette, so the title reads as chrome next to
         // the terminal's own foreground.
-        fill = hex(colors.rgb(8)),
+        fill = hex(colors.color(ColorSlot::Indexed(8))),
         esc = escape(&shown),
     );
 }
@@ -148,7 +149,7 @@ fn write_title(out: &mut String, title: &str, width: f32, colors: &Colors) {
 pub fn render_svg(
     rows: &[Vec<EmuCell>],
     cols: u16,
-    colors: &Colors,
+    colors: &dyn Emulator,
     title: Option<&str>,
 ) -> String {
     let nerd_font = NerdFont::new(rows, FONT_SIZE);
@@ -167,7 +168,7 @@ pub fn render_svg(
     let _ = write!(
         out,
         r#"<rect width="{width:.0}" height="{height:.0}" rx="8" fill="{}"/>"#,
-        hex(colors.background)
+        hex(colors.resolve(None, false))
     );
     for (i, dot) in ["#ff5f56", "#ffbd2e", "#27c93f"].iter().enumerate() {
         let cx = MARGIN_X + 5.0 + i as f32 * 20.0;
@@ -189,7 +190,7 @@ pub fn render_svg(
             while x + run < cols && bg_of(cell_at(row, x + run), colors) == bg {
                 run += 1;
             }
-            if bg != colors.background {
+            if bg != colors.resolve(None, false) {
                 let rx = x0 + x as f32 * CELL_W;
                 let ry = y0 + y as f32 * CELL_H;
                 let rw = run as f32 * CELL_W;
@@ -266,8 +267,16 @@ pub fn render_svg(
 #[cfg(test)]
 mod tests {
     use super::*;
+    use crate::profile::{ColorSlot, Profile};
+    use crate::terminal::alacritty::AlacrittyEmu;
     use crate::terminal::cell::Color;
 
+    /// A real emulator: the renderer resolves through the same path a session
+    /// uses, so a stand-in could not drift from it.
+    fn colors() -> AlacrittyEmu {
+        AlacrittyEmu::new(10, 2, &Profile::default())
+    }
+
     fn cell(ch: &str, fg: Option<Color>, bg: Option<Color>) -> EmuCell {
         EmuCell {
             ch: ch.into(),
@@ -277,18 +286,67 @@ mod tests {
         }
     }
 
+    /// A program that repaints the terminal repaints the screenshot.
+    ///
+    /// The renderer draws what the terminal is currently showing, not what it
+    /// was configured with, so a background set with `OSC 11` is the one that
+    /// gets painted. Nothing else covers the path from an escape sequence to
+    /// a rendered pixel.
+    #[test]
+    fn a_screenshot_follows_colors_a_program_set() {
+        use crate::terminal::emu::Emulator;
+        let mut emu = colors();
+        let rows = vec![vec![cell("x", Some(Color::from_index(1)), None)]];
+
+        let before = render_svg(&rows, 1, &emu, None);
+        assert!(before.contains(&hex(Profile::default().colors.red)));
+        assert!(before.contains(&hex(Profile::default().colors.background)));
+
+        // The program picks its own background and recolors palette slot 1.
+        emu.process(b"\x1b]11;#3b0764\x07\x1b]4;1;#22c55e\x07");
+
+        let after = render_svg(&rows, 1, &emu, None);
+        assert!(
+            after.contains("#3b0764"),
+            "the window is painted with the background the program set"
+        );
+        assert!(
+            after.contains("#22c55e"),
+            "a cell follows the slot the program recolored"
+        );
+        assert!(
+            !after.contains(&hex(Profile::default().colors.red)),
+            "the configured red is no longer what slot 1 shows"
+        );
+    }
+
+    /// And a reset puts the configured colors back on screen.
+    #[test]
+    fn a_screenshot_returns_to_the_profile_after_a_reset() {
+        use crate::terminal::emu::Emulator;
+        let mut emu = colors();
+        let rows = vec![vec![cell("x", Some(Color::from_index(1)), None)]];
+
+        emu.process(b"\x1b]11;#3b0764\x07\x1b]4;1;#22c55e\x07");
+        emu.process(b"\x1b]111\x07\x1b]104;1\x07");
+
+        let after = render_svg(&rows, 1, &emu, None);
+        assert!(after.contains(&hex(Profile::default().colors.background)));
+        assert!(after.contains(&hex(Profile::default().colors.red)));
+    }
+
     #[test]
     fn emits_valid_svg_with_text_and_color() {
         let rows = vec![vec![
             cell("h", Some(Color::from_index(1)), None),
             cell("i", Some(Color::from_index(1)), None),
         ]];
-        let svg = render_svg(&rows, 2, &Colors::default(), None);
+        let svg = render_svg(&rows, 2, &colors(), None);
         assert!(svg.starts_with("<svg"));
         assert!(svg.ends_with("</svg>"));
         assert!(svg.contains("textLength"));
         assert!(
-            svg.contains(&hex(Colors::default().rgb(1))),
+            svg.contains(&hex(colors().color(ColorSlot::Indexed(1)))),
             "slot 1 is painted with the profile color"
         );
         assert!(svg.contains(">hi</text>"));
@@ -298,7 +356,7 @@ mod tests {
 
     #[test]
     fn emits_window_chrome() {
-        let svg = render_svg(&[vec![cell(" ", None, None)]], 1, &Colors::default(), None);
+        let svg = render_svg(&[vec![cell(" ", None, None)]], 1, &colors(), None);
         assert!(svg.contains("<circle"));
         assert!(svg.contains("#ff5f56"));
         assert!(svg.contains("#ffbd2e"));
@@ -307,7 +365,7 @@ mod tests {
 
     #[test]
     fn centers_the_text_font_box_in_each_cell() {
-        let svg = render_svg(&[vec![cell("x", None, None)]], 1, &Colors::default(), None);
+        let svg = render_svg(&[vec![cell("x", None, None)]], 1, &colors(), None);
         let expected_baseline = HEADER_H + FONT_BASELINE;
         assert!(svg.contains(&format!(r#"y="{expected_baseline:.2}""#)));
     }
@@ -315,7 +373,7 @@ mod tests {
     #[test]
     fn escapes_markup_characters() {
         let rows = vec![vec![cell("<", None, None)]];
-        let svg = render_svg(&rows, 1, &Colors::default(), None);
+        let svg = render_svg(&rows, 1, &colors(), None);
         assert!(svg.contains("&lt;"));
         assert!(!svg.contains("><</text>"));
     }
@@ -323,9 +381,9 @@ mod tests {
     #[test]
     fn background_run_emitted_for_non_default_bg() {
         let rows = vec![vec![cell(" ", None, Some(Color::from_index(4)))]];
-        let svg = render_svg(&rows, 1, &Colors::default(), None);
+        let svg = render_svg(&rows, 1, &colors(), None);
         assert!(
-            svg.contains(&hex(Colors::default().rgb(4))),
+            svg.contains(&hex(colors().color(ColorSlot::Indexed(4)))),
             "slot 4 is painted with the profile color"
         );
     }
@@ -338,7 +396,7 @@ mod tests {
             cell(glyph, None, None),
             cell("b", None, None),
         ]];
-        let svg = render_svg(&rows, 3, &Colors::default(), None);
+        let svg = render_svg(&rows, 3, &colors(), None);
 
         assert!(svg.contains(r#"<path id="nf-f115" d=""#));
         assert!(svg.contains(r##"<use href="#nf-f115""##));
@@ -353,7 +411,7 @@ mod tests {
         let svg = render_svg(
             &[vec![cell(glyph, None, None), cell(glyph, None, None)]],
             2,
-            &Colors::default(),
+            &colors(),
             None,
         );
 
@@ -364,12 +422,7 @@ mod tests {
     #[test]
     fn leaves_unknown_private_use_glyphs_as_text() {
         let glyph = "\u{10fffd}";
-        let svg = render_svg(
-            &[vec![cell(glyph, None, None)]],
-            1,
-            &Colors::default(),
-            None,
-        );
+        let svg = render_svg(&[vec![cell(glyph, None, None)]], 1, &colors(), None);
 
         assert!(svg.contains(glyph));
         assert!(!svg.contains("<defs>"));
@@ -382,8 +435,8 @@ mod tests {
     #[test]
     fn draws_the_window_title_centred_in_the_bar() {
         let rows = vec![vec![cell("x", None, None); 40]];
-        let bare = render_svg(&rows, 40, &Colors::default(), None);
-        let titled = render_svg(&rows, 40, &Colors::default(), Some("vim: notes.md"));
+        let bare = render_svg(&rows, 40, &colors(), None);
+        let titled = render_svg(&rows, 40, &colors(), Some("vim: notes.md"));
 
         assert!(
             !bare.contains("text-anchor=\"middle\""),
@@ -406,7 +459,7 @@ mod tests {
     fn truncates_a_title_that_does_not_fit() {
         let rows = vec![vec![cell("x", None, None); 20]];
         let long = "a-very-long-window-title-that-cannot-possibly-fit";
-        let svg = render_svg(&rows, 20, &Colors::default(), Some(long));
+        let svg = render_svg(&rows, 20, &colors(), Some(long));
 
         assert!(!svg.contains(long), "the full title cannot have been drawn");
         let drawn = svg
@@ -427,7 +480,7 @@ mod tests {
     #[test]
     fn budgets_a_wide_glyph_title_by_column() {
         let rows = vec![vec![cell("x", None, None); 24]];
-        let svg = render_svg(&rows, 24, &Colors::default(), Some(&"你".repeat(40)));
+        let svg = render_svg(&rows, 24, &colors(), Some(&"你".repeat(40)));
         let drawn = svg
             .split("text-anchor=\"middle\" xml:space=\"preserve\">")
             .nth(1)
@@ -455,12 +508,7 @@ mod tests {
     #[test]
     fn escapes_markup_in_the_title() {
         let rows = vec![vec![cell("x", None, None); 40]];
-        let svg = render_svg(
-            &rows,
-            40,
-            &Colors::default(),
-            Some("</text><script>x</script>"),
-        );
+        let svg = render_svg(&rows, 40, &colors(), Some("</text><script>x</script>"));
 
         assert!(!svg.contains("<script>"), "no injected element: {svg}");
         assert!(
diff --git a/crates/shell-use/src/session.rs b/crates/shell-use/src/session.rs
index 757af55..3565f60 100644
--- a/crates/shell-use/src/session.rs
+++ b/crates/shell-use/src/session.rs
@@ -28,8 +28,6 @@ pub struct TermState {
 
 pub struct Session {
     pub shell: Option<Shell>,
-    /// Settings this session was opened with, fixed for its lifetime.
-    pub profile: Profile,
     pub cols: u16,
     pub rows: u16,
     /// Per-class timeout defaults for the lifetime of this session.
@@ -82,7 +80,7 @@ impl Session {
         };
 
         let state = Arc::new(Mutex::new(TermState {
-            emu: Box::new(AlacrittyEmu::new(cols, rows, profile.scrollback)),
+            emu: Box::new(AlacrittyEmu::new(cols, rows, &profile)),
             tracker: CommandTracker::new(),
             last_change: Instant::now(),
             awaiting_start: None,
@@ -153,7 +151,6 @@ impl Session {
 
         Ok(Session {
             shell,
-            profile,
             cols,
             rows,
             timeouts,
diff --git a/crates/shell-use/src/terminal/alacritty.rs b/crates/shell-use/src/terminal/alacritty.rs
index 9949e04..cf27e53 100644
--- a/crates/shell-use/src/terminal/alacritty.rs
+++ b/crates/shell-use/src/terminal/alacritty.rs
@@ -12,9 +12,12 @@ use alacritty_terminal::term::cell::Flags as AlacFlags;
 use alacritty_terminal::term::test::TermSize;
 use alacritty_terminal::term::{Config as AlacConfig, Term};
 use alacritty_terminal::vte::ansi;
+use alacritty_terminal::vte::ansi::NamedColor;
+use alacritty_terminal::vte::ansi::Rgb as AlacRgb;
 
 use compact_str::{CompactString, ToCompactString};
 
+use crate::profile::{xterm_color, ColorSlot, Profile, Rgb};
 use crate::terminal::cell::{Attrs, Color, EmuCell, UnderlineStyle, CONTINUATION};
 use crate::terminal::emu::Emulator;
 
@@ -112,27 +115,52 @@ fn cell_from_alac(c: &alacritty_terminal::term::cell::Cell) -> EmuCell {
     }
 }
 
+/// Formats a color query's reply once the color is known. alacritty builds
+/// this closure with the query's own prefix and terminator already captured,
+/// so the answer echoes the form the program asked in.
+type ReplyFormat = Arc<dyn Fn(AlacRgb) -> String + Send + Sync>;
+
+/// One thing the terminal wants to say back to the PTY.
+///
+/// A color query cannot be answered where it arrives: the color lives in the
+/// terminal's own palette, and this listener is constructed before the
+/// terminal it listens to. It is parked as a [`Reply::Color`] and resolved by
+/// [`AlacrittyEmu::answer_queries`] once `process` returns.
+enum Reply {
+    Bytes(Vec<u8>),
+    Color(usize, ReplyFormat),
+}
+
+/// Queues what the terminal wants to say back to the PTY, in the order it
+/// decided to say it.
+///
+/// Answers and other replies share one queue because a program may pipeline
+/// several requests in a single write and match the answers up by position.
+/// The common idiom ends a batch of queries with a device attributes request,
+/// whose reply every terminal sends, and treats that reply as the end of the
+/// batch: an answer that arrived after it would look like the query went
+/// unanswered, and would then be read as though the user had typed it.
 #[derive(Default, Clone)]
 struct CaptureProxy {
-    pending: Arc<Mutex<Vec<u8>>>,
+    pending: Arc<Mutex<Vec<Reply>>>,
     title: Arc<Mutex<Option<String>>>,
 }
 
 impl EventListener for CaptureProxy {
     fn send_event(&self, ev: Event) {
-        match ev {
-            Event::PtyWrite(bytes) => {
-                if let Ok(mut buf) = self.pending.lock() {
-                    buf.extend_from_slice(bytes.as_bytes());
-                }
-            }
+        let reply = match ev {
+            Event::PtyWrite(bytes) => Reply::Bytes(bytes.as_bytes().to_vec()),
+            Event::ColorRequest(slot, format) => Reply::Color(slot, format),
             // `OSC 0` and `OSC 2` both arrive here, and so does a pop of the
             // title stack (`CSI 23 t`), which alacritty implements by setting
             // the title it popped. An empty payload means the same as a reset:
             // the program is asking for no title rather than for a blank one.
-            Event::Title(title) => self.set_title((!title.is_empty()).then_some(title)),
-            Event::ResetTitle => self.set_title(None),
-            _ => {}
+            Event::Title(title) => return self.set_title((!title.is_empty()).then_some(title)),
+            Event::ResetTitle => return self.set_title(None),
+            _ => return,
+        };
+        if let Ok(mut queue) = self.pending.lock() {
+            queue.push(reply);
         }
     }
 }
@@ -150,30 +178,81 @@ pub struct AlacrittyEmu {
     processor: ansi::Processor,
     cols: u16,
     rows: u16,
-    pending: Arc<Mutex<Vec<u8>>>,
+    pending: Arc<Mutex<Vec<Reply>>>,
     title: Arc<Mutex<Option<String>>>,
+    /// The settings this session was opened with. A program can shadow the
+    /// colors at runtime but never reach them, so a reset always has a value
+    /// to restore.
+    profile: Profile,
 }
 
 impl AlacrittyEmu {
-    pub fn new(cols: u16, rows: u16, scrollback: usize) -> Self {
+    pub fn new(cols: u16, rows: u16, profile: &Profile) -> Self {
         let size = TermSize::new(cols as usize, rows as usize);
-        let config = AlacConfig {
-            scrolling_history: scrollback,
+        let alac_config = AlacConfig {
+            scrolling_history: profile.scrollback,
             ..Default::default()
         };
-        let pending: Arc<Mutex<Vec<u8>>> = Arc::default();
+        let pending: Arc<Mutex<Vec<Reply>>> = Arc::default();
         let title: Arc<Mutex<Option<String>>> = Arc::default();
         let proxy = CaptureProxy {
             pending: pending.clone(),
             title: title.clone(),
         };
         AlacrittyEmu {
-            term: Term::new(config, &size, proxy),
+            term: Term::new(alac_config, &size, proxy),
             processor: ansi::Processor::new(),
             cols,
             rows,
             pending,
             title,
+            profile: *profile,
+        }
+    }
+
+    /// Resolve any color queries parked while the last chunk was parsed.
+    ///
+    /// Each answer replaces the query where it sits in the queue, so replies
+    /// leave in the order the program asked for them. Resolving them at the
+    /// end of the chunk rather than where they arrived is what makes this
+    /// necessary: the palette lives in the terminal, which the listener that
+    /// received the query cannot reach.
+    fn answer_queries(&mut self) {
+        let parked: Vec<Reply> = match self.pending.lock() {
+            Ok(mut queue) => {
+                if !queue.iter().any(|r| matches!(r, Reply::Color(..))) {
+                    return;
+                }
+                std::mem::take(&mut queue)
+            }
+            Err(_) => return,
+        };
+        let resolved: Vec<Reply> = parked
+            .into_iter()
+            .map(|reply| match reply {
+                Reply::Bytes(bytes) => Reply::Bytes(bytes),
+                Reply::Color(index, format) => {
+                    let slot = match index {
+                        i if i == NamedColor::Foreground as usize => ColorSlot::Foreground,
+                        i if i == NamedColor::Background as usize => ColorSlot::Background,
+                        i if i == NamedColor::Cursor as usize => ColorSlot::Cursor,
+                        i => ColorSlot::Indexed(i as u8),
+                    };
+                    let c = self.color(slot);
+                    Reply::Bytes(
+                        format(AlacRgb {
+                            r: c.r,
+                            g: c.g,
+                            b: c.b,
+                        })
+                        .into_bytes(),
+                    )
+                }
+            })
+            .collect();
+        if let Ok(mut queue) = self.pending.lock() {
+            // Anything queued meanwhile was asked for later, so it goes after.
+            queue.splice(0..0, resolved);
         }
     }
 
@@ -195,13 +274,25 @@ impl AlacrittyEmu {
 impl Emulator for AlacrittyEmu {
     fn process(&mut self, bytes: &[u8]) {
         self.processor.advance(&mut self.term, bytes);
+        // Queries are answered here rather than in the listener because the
+        // terminal holding the palette is only in scope once parsing is done.
+        self.answer_queries();
     }
 
     fn take_pending_writes(&mut self) -> Vec<u8> {
-        match self.pending.lock() {
-            Ok(mut buf) => std::mem::take(&mut *buf),
-            Err(_) => Vec::new(),
-        }
+        let queued = match self.pending.lock() {
+            Ok(mut queue) => std::mem::take(&mut *queue),
+            Err(_) => return Vec::new(),
+        };
+        queued
+            .into_iter()
+            .flat_map(|reply| match reply {
+                Reply::Bytes(bytes) => bytes,
+                // `answer_queries` runs at the end of every chunk, so a query
+                // is always resolved before anything can drain it.
+                Reply::Color(..) => Vec::new(),
+            })
+            .collect()
     }
 
     fn title(&self) -> Option<String> {
@@ -219,6 +310,34 @@ impl Emulator for AlacrittyEmu {
         (self.cols, self.rows)
     }
 
+    /// alacritty stores only what a program set, leaving every other slot
+    /// empty, so an empty slot falls through to the profile, and then to the
+    /// xterm table for an index the profile does not name.
+    ///
+    /// The indices are alacritty's own: it lays its table out as the
+    /// 256-color palette followed by the dynamic colors, which is why the
+    /// three are 256, 257, 258. That layout stops here.
+    fn color(&self, slot: ColorSlot) -> Rgb {
+        let colors = &self.profile.colors;
+        let (index, configured) = match slot {
+            ColorSlot::Indexed(index) => (
+                index as usize,
+                colors
+                    .ansi()
+                    .get(index as usize)
+                    .copied()
+                    .unwrap_or_else(|| xterm_color(index)),
+            ),
+            ColorSlot::Foreground => (NamedColor::Foreground as usize, colors.foreground),
+            ColorSlot::Background => (NamedColor::Background as usize, colors.background),
+            ColorSlot::Cursor => (NamedColor::Cursor as usize, colors.cursor),
+        };
+        match self.term.colors()[index] {
+            Some(set) => Rgb::new(set.r, set.g, set.b),
+            None => configured,
+        }
+    }
+
     fn cursor(&self) -> (u16, u16) {
         let p = self.term.grid().cursor.point;
         let y = p.line.0.max(0).min(self.rows as i32 - 1) as u16;
@@ -243,5 +362,55 @@ impl Emulator for AlacrittyEmu {
 mod tests {
     use super::*;
 
-    crate::emulator_conformance_tests!(|c, r, s| Box::new(AlacrittyEmu::new(c, r, s)));
+    crate::emulator_conformance_tests!(|c, r, p| Box::new(AlacrittyEmu::new(c, r, p)));
+
+    /// Every slot a program can address resolves, so a query always has an
+    /// answer and a reset always has something to restore. The profile names
+    /// sixteen; everything above falls through to the xterm table.
+    #[test]
+    fn every_slot_resolves_through_the_profile_then_xterm() {
+        use crate::profile::{Colors, Rgb};
+        let profile = Profile {
+            colors: Colors {
+                red: Rgb::new(1, 2, 3),
+                background: Rgb::new(4, 5, 6),
+                ..Default::default()
+            },
+            ..Default::default()
+        };
+        let emu = AlacrittyEmu::new(10, 2, &profile);
+
+        assert_eq!(
+            emu.color(ColorSlot::Indexed(1)),
+            Rgb::new(1, 2, 3),
+            "the profile names slot 1"
+        );
+        assert_eq!(emu.color(ColorSlot::Background), Rgb::new(4, 5, 6));
+        assert_eq!(
+            emu.color(ColorSlot::Foreground),
+            Colors::default().foreground,
+            "an unset profile color keeps its default"
+        );
+        for index in 16u8..=255 {
+            assert_eq!(
+                emu.color(ColorSlot::Indexed(index)),
+                xterm_color(index),
+                "slot {index} is not the profile's to name"
+            );
+        }
+    }
+
+    /// A program's color outranks the profile until it is reset, at which
+    /// point the profile shows through again.
+    #[test]
+    fn a_program_color_outranks_the_profile_until_reset() {
+        let mut emu = AlacrittyEmu::new(10, 2, &Profile::default());
+        let configured = emu.color(ColorSlot::Background);
+
+        emu.process(b"\x1b]11;#123456\x07");
+        assert_eq!(emu.color(ColorSlot::Background), Rgb::new(0x12, 0x34, 0x56));
+
+        emu.process(b"\x1b]111\x07");
+        assert_eq!(emu.color(ColorSlot::Background), configured);
+    }
 }
diff --git a/crates/shell-use/src/terminal/conformance.rs b/crates/shell-use/src/terminal/conformance.rs
index 24bc92f..637789b 100644
--- a/crates/shell-use/src/terminal/conformance.rs
+++ b/crates/shell-use/src/terminal/conformance.rs
@@ -16,7 +16,7 @@
 //! the test pins only the part that is universal and says why it stops short.
 
 /// Generates the conformance tests for one backend. `$make` builds a boxed
-/// emulator from `(cols, rows, scrollback)`.
+/// emulator from `(cols, rows, &Profile)`.
 ///
 /// The body is fully path-qualified because it expands into the caller's
 /// module; it must not collide with whatever that module already imports.
@@ -28,8 +28,27 @@ macro_rules! emulator_conformance_tests {
             rows: u16,
             scrollback: usize,
         ) -> Box<dyn $crate::terminal::emu::Emulator> {
-            let make: fn(u16, u16, usize) -> Box<dyn $crate::terminal::emu::Emulator> = $make;
-            make(cols, rows, scrollback)
+            conformance_emu_with(
+                cols,
+                rows,
+                $crate::profile::Profile {
+                    scrollback,
+                    ..Default::default()
+                },
+            )
+        }
+
+        fn conformance_emu_with(
+            cols: u16,
+            rows: u16,
+            profile: $crate::profile::Profile,
+        ) -> Box<dyn $crate::terminal::emu::Emulator> {
+            let make: fn(
+                u16,
+                u16,
+                &$crate::profile::Profile,
+            ) -> Box<dyn $crate::terminal::emu::Emulator> = $make;
+            make(cols, rows, &profile)
         }
 
         /// Row text with trailing blanks removed, for readable assertions.
@@ -542,6 +561,284 @@ macro_rules! emulator_conformance_tests {
             );
         }
 
+        /// A color query is answered with the session's configured color.
+        ///
+        /// Programs query the background to decide whether they are on a light
+        /// or a dark terminal. A backend that stays silent leaves them blocked
+        /// until they time out and guess.
+        #[test]
+        fn conformance_color_queries_are_answered() {
+            use $crate::profile::{Colors, Profile, Rgb};
+            let profile = Profile {
+                colors: Colors {
+                    background: Rgb::new(0x12, 0x34, 0x56),
+                    red: Rgb::new(0xab, 0xcd, 0xef),
+                    ..Default::default()
+                },
+                ..Default::default()
+            };
+            let mut e = conformance_emu_with(10, 4, profile);
+            let _ = e.take_pending_writes();
+
+            e.process(b"\x1b]11;?\x07");
+            assert_eq!(
+                String::from_utf8_lossy(&e.take_pending_writes()),
+                "\x1b]11;rgb:1212/3434/5656\x07",
+                "OSC 11 must report the configured background"
+            );
+
+            e.process(b"\x1b]4;1;?\x07");
+            assert_eq!(
+                String::from_utf8_lossy(&e.take_pending_writes()),
+                "\x1b]4;1;rgb:abab/cdcd/efef\x07",
+                "OSC 4 must report the configured palette entry"
+            );
+        }
+
+        /// A reply uses the terminator the query used. A program that reads
+        /// until the terminator it sent would otherwise wait for one that
+        /// never comes.
+        #[test]
+        fn conformance_a_color_reply_echoes_the_terminator() {
+            let mut e = conformance_emu(10, 4, 100);
+            let _ = e.take_pending_writes();
+
+            e.process(b"\x1b]11;?\x07");
+            let bel = e.take_pending_writes();
+            assert!(
+                bel.ends_with(b"\x07"),
+                "a BEL query is answered with BEL: {:?}",
+                String::from_utf8_lossy(&bel)
+            );
+
+            e.process(b"\x1b]11;?\x1b\\");
+            let st = e.take_pending_writes();
+            assert!(
+                st.ends_with(b"\x1b\\"),
+                "an ST query is answered with ST: {:?}",
+                String::from_utf8_lossy(&st)
+            );
+        }
+
+        /// Replies leave in the order the program asked for them.
+        ///
+        /// A batch of queries is commonly ended with a device attributes
+        /// request, whose reply every terminal sends, and the reply to it is
+        /// read as the end of the batch. An answer that arrived after it would
+        /// look like the query went unanswered, and would then be read as
+        /// though the user had typed it.
+        #[test]
+        fn conformance_replies_keep_the_order_they_were_asked_in() {
+            let mut e = conformance_emu(10, 4, 100);
+            let _ = e.take_pending_writes();
+
+            e.process(b"\x1b]11;?\x07\x1b[c");
+            let asked_color_first = e.take_pending_writes();
+            let color = asked_color_first
+                .windows(2)
+                .position(|w| w == b"]1")
+                .expect("a color reply");
+            let attributes = asked_color_first
+                .windows(2)
+                .position(|w| w == b"[?")
+                .expect("a device attributes reply");
+            assert!(
+                color < attributes,
+                "the color was asked for first, so it is answered first: {:?}",
+                String::from_utf8_lossy(&asked_color_first)
+            );
+
+            e.process(b"\x1b[c\x1b]11;?\x07");
+            let asked_color_second = e.take_pending_writes();
+            let color = asked_color_second
+                .windows(2)
+                .position(|w| w == b"]1")
+                .expect("a color reply");
+            let attributes = asked_color_second
+                .windows(2)
+                .position(|w| w == b"[?")
+                .expect("a device attributes reply");
+            assert!(
+                attributes < color,
+                "and asked for second, it is answered second: {:?}",
+                String::from_utf8_lossy(&asked_color_second)
+            );
+        }
+
+        /// A program can shadow a color, and a reset puts the configured one
+        /// back. The configured color is never reachable, so a reset always
+        /// has something to restore.
+        #[test]
+        fn conformance_a_color_set_is_undone_by_a_reset() {
+            use $crate::profile::{Colors, Profile, Rgb};
+            let configured = Rgb::new(0x11, 0x22, 0x33);
+            let profile = Profile {
+                colors: Colors {
+                    background: configured,
+                    ..Default::default()
+                },
+                ..Default::default()
+            };
+            let mut e = conformance_emu_with(10, 4, profile);
+            let background = $crate::profile::ColorSlot::Background;
+            assert_eq!(e.color(background), configured);
+
+            e.process(b"\x1b]11;#654321\x07");
+            assert_eq!(
+                e.color(background),
+                Rgb::new(0x65, 0x43, 0x21),
+                "a set shadows the configured color"
+            );
+
+            e.process(b"\x1b]111\x07");
+            assert_eq!(
+                e.color(background),
+                configured,
+                "OSC 111 restores the configured color"
+            );
+
+            // The same for a palette entry, which resets with OSC 104.
+            e.process(b"\x1b]4;2;#010203\x07");
+            assert_eq!(
+                e.color($crate::profile::ColorSlot::Indexed(2)),
+                Rgb::new(1, 2, 3)
+            );
+            e.process(b"\x1b]104;2\x07");
+            assert_eq!(
+                e.color($crate::profile::ColorSlot::Indexed(2)),
+                Colors::default().green
+            );
+        }
+
+        /// Each dynamic color is addressed by its own sequence, and each is
+        /// reset by its own.
+        ///
+        /// `OSC 11` is the one programs reach for, so it is easy to wire that
+        /// up and leave the foreground or the cursor answering the wrong slot.
+        #[test]
+        fn conformance_each_dynamic_color_is_separately_addressable() {
+            use $crate::profile::ColorSlot;
+            let mut e = conformance_emu(10, 4, 100);
+            let before = [
+                e.color(ColorSlot::Foreground),
+                e.color(ColorSlot::Background),
+                e.color(ColorSlot::Cursor),
+            ];
+
+            // Set all three to distinct colors, then check none bled into
+            // another.
+            e.process(b"\x1b]10;#111111\x07\x1b]11;#222222\x07\x1b]12;#333333\x07");
+            assert_eq!(e.color(ColorSlot::Foreground), Rgb::new(0x11, 0x11, 0x11));
+            assert_eq!(e.color(ColorSlot::Background), Rgb::new(0x22, 0x22, 0x22));
+            assert_eq!(e.color(ColorSlot::Cursor), Rgb::new(0x33, 0x33, 0x33));
+
+            // And each reset frees only its own slot.
+            e.process(b"\x1b]110\x07");
+            assert_eq!(e.color(ColorSlot::Foreground), before[0], "110 resets fg");
+            assert_eq!(
+                e.color(ColorSlot::Background),
+                Rgb::new(0x22, 0x22, 0x22),
+                "110 must leave the background alone"
+            );
+
+            e.process(b"\x1b]112\x07");
+            assert_eq!(
+                e.color(ColorSlot::Cursor),
+                before[2],
+                "112 resets the cursor"
+            );
+            assert_eq!(
+                e.color(ColorSlot::Background),
+                Rgb::new(0x22, 0x22, 0x22),
+                "112 must leave the background alone"
+            );
+
+            e.process(b"\x1b]111\x07");
+            assert_eq!(e.color(ColorSlot::Background), before[1], "111 resets bg");
+        }
+
+        /// Every dynamic color answers a query, not just the background.
+        #[test]
+        fn conformance_every_dynamic_color_answers_a_query() {
+            let mut e = conformance_emu(10, 4, 100);
+            let _ = e.take_pending_writes();
+
+            e.process(b"\x1b]10;#010203\x07\x1b]11;#040506\x07\x1b]12;#070809\x07");
+            let _ = e.take_pending_writes();
+
+            for (query, expected) in [
+                (&b"\x1b]10;?\x07"[..], "\x1b]10;rgb:0101/0202/0303\x07"),
+                (b"\x1b]11;?\x07", "\x1b]11;rgb:0404/0505/0606\x07"),
+                (b"\x1b]12;?\x07", "\x1b]12;rgb:0707/0808/0909\x07"),
+            ] {
+                e.process(query);
+                assert_eq!(
+                    String::from_utf8_lossy(&e.take_pending_writes()),
+                    expected,
+                    "querying {:?}",
+                    String::from_utf8_lossy(query)
+                );
+            }
+        }
+
+        /// `OSC 104` with no index resets the whole palette, and leaves the
+        /// three dynamic colors alone: they have their own resets.
+        #[test]
+        fn conformance_a_bare_palette_reset_spares_the_dynamic_colors() {
+            use $crate::profile::ColorSlot;
+            let mut e = conformance_emu(10, 4, 100);
+            let configured_red = e.color(ColorSlot::Indexed(1));
+
+            e.process(b"\x1b]4;1;#111111;200;#222222\x07\x1b]11;#333333\x07");
+            assert_eq!(e.color(ColorSlot::Indexed(1)), Rgb::new(0x11, 0x11, 0x11));
+            assert_eq!(e.color(ColorSlot::Indexed(200)), Rgb::new(0x22, 0x22, 0x22));
+
+            e.process(b"\x1b]104\x07");
+            assert_eq!(e.color(ColorSlot::Indexed(1)), configured_red);
+            assert_eq!(
+                e.color(ColorSlot::Background),
+                Rgb::new(0x33, 0x33, 0x33),
+                "a palette reset is not a background reset"
+            );
+        }
+
+        /// An unconfigured palette entry still answers, from the table the
+        /// specification defines for it.
+        #[test]
+        fn conformance_an_unconfigured_index_resolves_from_the_spec_table() {
+            use $crate::profile::Rgb;
+            let e = conformance_emu(10, 4, 100);
+            assert_eq!(
+                e.color($crate::profile::ColorSlot::Indexed(196)),
+                Rgb::new(255, 0, 0),
+                "index 196 is pure red in the xterm color cube"
+            );
+            assert_eq!(
+                e.color($crate::profile::ColorSlot::Indexed(232)),
+                Rgb::new(8, 8, 8),
+                "the gray ramp starts at 8"
+            );
+        }
+
+        /// A cell records which slot it chose, never a color, so what it
+        /// paints follows whatever that slot currently holds.
+        #[test]
+        fn conformance_a_cell_follows_its_slot() {
+            use $crate::profile::Rgb;
+            let mut e = conformance_emu(10, 4, 100);
+            e.process(b"\x1b[31mR");
+            let cell = e.viewable_rows()[0][0].clone();
+
+            let before = e.resolve(cell.fg, true);
+            e.process(b"\x1b]4;1;#0a0b0c\x07");
+            assert_eq!(
+                e.resolve(cell.fg, true),
+                Rgb::new(0x0a, 0x0b, 0x0c),
+                "recoloring the slot recolors the cell that chose it"
+            );
+            assert_ne!(before, e.resolve(cell.fg, true));
+        }
+
         /// The alternate screen hides primary content and restores it on exit.
         #[test]
         fn conformance_alt_screen_round_trip() {
diff --git a/crates/shell-use/src/terminal/emu.rs b/crates/shell-use/src/terminal/emu.rs
index d8bc7f7..60e4ccd 100644
--- a/crates/shell-use/src/terminal/emu.rs
+++ b/crates/shell-use/src/terminal/emu.rs
@@ -10,7 +10,8 @@
 //! identical shell-integration behavior by construction rather than by
 //! reimplementation.
 
-use crate::terminal::cell::EmuCell;
+use crate::profile::{ColorSlot, Rgb};
+use crate::terminal::cell::{Color, EmuCell};
 
 /// A headless terminal emulator: bytes in, cell grid out.
 ///
@@ -48,4 +49,38 @@ pub trait Emulator: Send {
 
     /// Scrollback history followed by the visible screen.
     fn full_rows(&self) -> Vec<Vec<EmuCell>>;
+
+    /// The color a slot is currently showing.
+    ///
+    /// Programs move these with `OSC 4` (palette) and `OSC 10/11/12` (default
+    /// foreground, background, cursor), and put them back with `OSC 104` and
+    /// `OSC 110/111/112`. A slot nothing has overridden shows the color the
+    /// session's profile gives it, so a reset always has something to restore
+    /// and this always has an answer.
+    ///
+    /// Backends answer color *queries* themselves, through
+    /// [`Emulator::take_pending_writes`], because each one already parses the
+    /// sequence and knows which terminator the query used. This reports the
+    /// same colors, so a screenshot and `expect --fg/--bg` agree with what a
+    /// program was told.
+    ///
+    fn color(&self, slot: ColorSlot) -> Rgb;
+
+    /// Resolve a cell's color, where `None` is the terminal default.
+    ///
+    /// The grid records which slot a cell chose, never a color, so this is
+    /// where a cell becomes something to paint or compare. Provided rather
+    /// than required so every backend resolves a cell identically.
+    fn resolve(&self, color: Option<Color>, is_fg: bool) -> Rgb {
+        match color {
+            None => self.color(if is_fg {
+                ColorSlot::Foreground
+            } else {
+                ColorSlot::Background
+            }),
+            Some(Color::Named(n)) => self.color(ColorSlot::Indexed(n.index())),
+            Some(Color::Idx(i)) => self.color(ColorSlot::Indexed(i)),
+            Some(Color::Rgb(r, g, b)) => Rgb::new(r, g, b),
+        }
+    }
 }