fix(wsl): forward truecolor capability into guest shells

architecture/notes/nebula_app/platform/2026-09-23-local-color-capabilities.md

@@ -28,8 +28,8 @@ model choice and Codex version still control whether its animation runs.
 
 After refreshing a local Windows environment, fill missing `TERM` with
 `xterm-256color` and missing `COLORTERM` with `truecolor`. Preserve explicit
-case-insensitive overrides and `NO_COLOR`/`FORCE_COLOR`. Keep the actual Pebrel
-terminal identity. Existing OSC color-query and rendering paths remain authoritative.
+case-insensitive overrides and `NO_COLOR`/`FORCE_COLOR`. Forward `COLORTERM` through the existing WSL environment allowlist, preserving
+explicit forwarding flags. Keep the actual Pebrel terminal identity. Existing OSC color-query and rendering paths remain authoritative.
 
 ## Rejected alternatives
 
@@ -50,7 +50,9 @@ Hook lifetime fix is unrelated to this environment declaration.
 Eight platform-environment tests pass, including an actual child launched with
 an explicitly complete environment. VT replay preserves message surfaces and
 Braille stars for all fifteen built-in themes, plus all 225 theme-switch pairs.
-These are capability/rendering tests, not a full live Codex animation acceptance.
+A native Debian control returned no `COLORTERM` without forwarding and
+`truecolor` with it. These are capability/rendering tests, not a full live Codex
+animation acceptance.
 
 ## Supersedes
 

nebula_app/src/agent_env.rs

@@ -170,6 +170,9 @@ const WSLENV_ENTRIES: &[&str] = &[
     crate::ai_hook::LEGACY_PANE_ENV,
     TERM_PROGRAM_ENV,
     TERM_PROGRAM_VERSION_ENV,
+    // WSL otherwise falls back to a 256-color TERM despite the host supporting
+    // truecolor. Keep the capability declaration; do not spoof another terminal.
+    "COLORTERM",
     "PEBREL_CLI/p",
     "PEBREL_BIN_DIR/p",
     PROCESS_ENV,
@@ -311,6 +314,27 @@ mod tests {
         assert!(names.contains(&BIN_DIR_ENV), "{BIN_DIR_ENV} missing: {names:?}");
         assert!(names.contains(&PROCESS_ENV), "{PROCESS_ENV} missing: {names:?}");
         assert!(names.contains(&crate::runtime_api::ENDPOINT_ENV));
+        assert!(names.contains(&"COLORTERM"));
+    }
+
+    #[cfg(windows)]
+    #[test]
+    fn wsl_receives_truecolor_without_replacing_an_explicit_forwarding_rule() {
+        let mut env = HashMap::from([
+            ("COLORTERM".to_owned(), "truecolor".to_owned()),
+            ("WSLENV".to_owned(), "KEEP/p".to_owned()),
+        ]);
+        apply(&mut env, 8);
+        assert_eq!(env["COLORTERM"], "truecolor");
+        assert!(env["WSLENV"].split(':').any(|entry| entry == "COLORTERM"));
+        assert!(env["WSLENV"].split(':').any(|entry| entry == "KEEP/p"));
+        env.insert("WSLENV".into(), "KEEP/p:COLORTERM/u".into());
+        env.insert("COLORTERM".into(), "24bit".into());
+        apply(&mut env, 8);
+        assert_eq!(env["COLORTERM"], "24bit");
+        let entries: Vec<_> =
+            env["WSLENV"].split(':').filter(|entry| variable_name(entry) == "COLORTERM").collect();
+        assert_eq!(entries, ["COLORTERM/u"]);
     }
 
     #[cfg(windows)]