dsh-web-icon-indicator 0.4.1 → 0.5.0

package/lib/index.js

@@ -40,10 +40,20 @@
  * Configuration object (all optional):
  *   iconsDir       Absolute directory holding base.svg. Default `<package>/icons/`.
  *   statusPath     JSON status endpoint path. Default `/dsh-web-icon-status.json`.
+ *                  Registration-time: composition entry only (never settings.yaml).
  *   iconPathPrefix URL prefix for static icon files. Default `/dsh-web-icon-indicator`.
+ *                  Registration-time: composition entry only (never settings.yaml).
  *   askingHoldMs   Minimum visibility for the asking state (ms). Default 3500.
  *   doneHoldMs     How long the done state stays before falling back to idle.
  *                  Default 5000.
+ *   defaultColor   Default icon color — the idle whale's primary color, as
+ *                  `#rgb` / `#rrggbb`. Absent = the idle state's own colors[0]
+ *                  (today's behavior). Give each DSH instance (its own profile /
+ *                  settings.yaml) a different value to tell their browser tabs
+ *                  apart. A value perceptually too close to another state's
+ *                  color raises a WARNING — surfaced in the settings card, in
+ *                  the host log, and as `warnings` on the status endpoint — but
+ *                  is still honored.
  *   states         Per-state visual config, keyed by state name:
  *                    states[idle]    = { effect, colors[], speed? }
  *                    states[running] = { effect, colors[], speed? }
@@ -121,8 +131,18 @@ const STATE_CONFIG_SCHEMA = z.object({
 const CONFIG_SCHEMA = z.object({
   askingHoldMs: z.number().min(0).default(DEFAULTS.askingHoldMs),
   doneHoldMs: z.number().min(0).default(DEFAULTS.doneHoldMs),
-  statusPath: z.string().default(DEFAULTS.statusPath),
-  iconPathPrefix: z.string().default(DEFAULTS.iconPathPrefix),
+  // Default icon color (`#rgb` / `#rrggbb`). Deliberately WITHOUT a schema
+  // default: an absent value keeps the idle state's own colors[0], exactly as
+  // before this key existed. `resolveConfig` folds a valid value into
+  // `states.idle.colors[0]` and drops an invalid one with a warning.
+  defaultColor: z.string(),
+  // `statusPath` / `iconPathPrefix` are deliberately NOT part of this schema.
+  // They are baked at registration time (the route table and the injected
+  // script's URLs are built in apply()), so a settings-document change to them
+  // could never take effect: the browser would poll the new path while the
+  // server still served the old one — a dead favicon. Keeping them out of the
+  // schema means the settings surface cannot advertise a key it cannot honor;
+  // they stay composition-entry only (see the README config table).
   iconsDir: z.string(),
   // dict (not a four-key object): the user layer may override only some
   // states; the plugin merges the resolved value over DEFAULTS anyway.
@@ -143,6 +163,7 @@ const INJECTED_SCRIPT = `
     var BIG_NUM_MIN = 2;     // show the full-frame number while more than one agent is active
     var BIG_NUM_RX = 11;     // count-block corner radius (demo/badge.html bigNum channel)
     var ANIM_START = null;   // wall-clock start of the current loop (hidden-tab fallback)
+    var FAILED = false;      // status poll currently failing (restore once per outage)
     var STATUS_PATH = "__STATUS_PATH__";
     var BASE_PATH = "__BASE_PATH__";
     var CFG = __CFG__;          // { states: { idle:{effect,colors,speed}, running:…, asking:…, done:… } }
@@ -155,13 +176,68 @@ const INJECTED_SCRIPT = `
     // Whale geometry (used as the transform pivot for scale/translate effects).
     var CX = 27.889625, CY = 24.952640;
 
+    // Every request this script makes is deadline-bounded: a fetch that hangs
+    // (half-open TCP, a suspended host, a captive portal) would otherwise hold
+    // the poll chain and the base.svg load forever, freezing the icon with no
+    // recovery. Aborting surfaces as a rejection, so the existing retry paths
+    // (poll keeps its interval; base.svg retries on the next tick) take over.
+    function timedFetch(url, init) {
+      if (typeof AbortController === "undefined") return fetch(url, init);
+      var ctrl = new AbortController();
+      var timer = setTimeout(function () { try { ctrl.abort(); } catch (e) {} }, 8000);
+      var opts = init || {};
+      opts.signal = ctrl.signal;
+      return fetch(url, opts).then(
+        function (r) { clearTimeout(timer); return r; },
+        function (e) { clearTimeout(timer); throw e; }
+      );
+    }
+
+    // Capture the shell's own favicon ONCE, together with an offline-safe
+    // data-URI copy of it. The copy matters: while the DSH host is stopped
+    // the original href (a URL served by that same host) is unreachable, so
+    // writing it back would blank the tab — the "backend stopped, icon lost"
+    // bug. data: URIs render without any network, so restore() below only
+    // ever writes those.
     function captureOriginal() {
+      if (ORIGINAL) return;
       var link = document.querySelector("link[rel='icon']");
-      if (link && ORIGINAL === null) ORIGINAL = { href: link.getAttribute("href") || "", type: link.getAttribute("type") || "" };
+      if (!link) return;
+      var href = link.getAttribute("href") || "";
+      ORIGINAL = { href: href, type: link.getAttribute("type") || "", data: null };
+      if (/^data:/i.test(href)) { ORIGINAL.data = href; return; }
+      // Best effort: fetch the original icon and convert it to a data: URI
+      // (any image type — blob -> FileReader). Environments without
+      // Blob/FileReader, or a failed fetch, leave data null; restore() then
+      // keeps the last plugin frame instead of risking a dead URL.
+      try {
+        if (!href || typeof Blob === "undefined" || typeof FileReader === "undefined") return;
+        timedFetch(href)
+          .then(function (r) { if (!r.ok) throw new Error("orig " + r.status); return r.blob(); })
+          .then(function (blob) {
+            return new Promise(function (resolve, reject) {
+              var fr = new FileReader();
+              fr.onload = function () { resolve(String(fr.result)); };
+              fr.onerror = function () { reject(fr.error || new Error("read failed")); };
+              fr.readAsDataURL(blob);
+            });
+          })
+          .then(function (uri) {
+            if (ORIGINAL && uri && uri.lastIndexOf("data:", 0) === 0) ORIGINAL.data = uri;
+          })
+          .catch(function () {});
+      } catch (e) {}
     }
+    // Offline-safe restore: prefer the cached data-URI copy of the original
+    // icon, then the original href when it is itself a data: URI. With
+    // neither available, keep the current frame (also a data: URI) — never
+    // write a server URL here, it is unreachable exactly when this runs.
     function restore() {
       var link = document.querySelector("link[rel='icon']");
-      if (link && ORIGINAL) { link.setAttribute("href", ORIGINAL.href); if (ORIGINAL.type) link.setAttribute("type", ORIGINAL.type); }
+      if (!link || !ORIGINAL) return;
+      var uri = ORIGINAL.data || (/^data:/i.test(ORIGINAL.href) ? ORIGINAL.href : null);
+      if (!uri) return;
+      try { link.setAttribute("href", uri); if (ORIGINAL.type) link.setAttribute("type", ORIGINAL.type); } catch (e) {}
     }
     function linkEl() { return document.querySelector("link[rel='icon']"); }
     function setHref(uri) {
@@ -224,6 +300,27 @@ const INJECTED_SCRIPT = `
     }
 
     // ---- svg frame builder --------------------------------------------------
+    // Frame-URI cache. The base template is re-read and re-encoded on every
+    // animation frame, but most effects cycle through a tiny set of fills
+    // (static → 1, blink → 2, breath/geometric effects → 1 per color pair), so
+    // the encoded data URI is stable and can be memoized. rainbow is the
+    // exception — its fill is a fresh hue every frame — and is left uncached so
+    // the map can never grow without bound.
+    var URI_CACHE = new Map();
+    function cachedUri(kind, fill, build) {
+      var key = kind + "|" + fill;
+      var hit = URI_CACHE.get(key);
+      if (hit === undefined) {
+        hit = build();
+        // Keep the cache small (state count × a handful of colors); a settings
+        // edit can introduce new colors, and this script runs for the life of
+        // the tab.
+        if (URI_CACHE.size > 64) URI_CACHE.clear();
+        URI_CACHE.set(key, hit);
+      }
+      return hit;
+    }
+
     // Full-frame activity count ("满幅数字", per demo/badge.html bigNum
     // channel): while more than one agent is active the whole icon becomes a
     // state-colored rounded block with a bold count — no whale is drawn, so
@@ -236,22 +333,28 @@ const INJECTED_SCRIPT = `
     // cropping (mirrors the demo's svgFrame showWhale=false branch).
     function bigNumUri(fill) {
       var text = String(ACTIVE > 99 ? "99+" : ACTIVE);
-      var chars = text.length;
-      var fs = chars === 1 ? 26 : chars === 2 ? 20 : 15.5;
-      var rgb = hexToRgb(fill);
-      var lum = (0.299 * rgb[0] + 0.587 * rgb[1] + 0.114 * rgb[2]) / 255;
-      var fg = lum > 0.6 ? "#111111" : "#FFFFFF"; // auto-contrast on the state color
-      var svg = '<svg xmlns="http://www.w3.org/2000/svg" width="50" height="50" viewBox="0 0 50 50" fill="none">' +
-        '<rect x="0" y="0" width="50" height="50" rx="' + BIG_NUM_RX + '" fill="' + fill + '"/>' +
-        '<text x="25" y="' + (25 + fs * 0.34).toFixed(1) + '" text-anchor="middle" font-family="system-ui, sans-serif" font-size="' + fs + '" font-weight="800" fill="' + fg + '">' + text + '</text>' +
-        '</svg>';
-      return "data:image/svg+xml," + encodeURIComponent(svg);
+      return cachedUri("n" + text, fill, function () {
+        var chars = text.length;
+        var fs = chars === 1 ? 26 : chars === 2 ? 20 : 15.5;
+        var rgb = hexToRgb(fill);
+        var lum = (0.299 * rgb[0] + 0.587 * rgb[1] + 0.114 * rgb[2]) / 255;
+        var fg = lum > 0.6 ? "#111111" : "#FFFFFF"; // auto-contrast on the state color
+        var svg = '<svg xmlns="http://www.w3.org/2000/svg" width="50" height="50" viewBox="0 0 50 50" fill="none">' +
+          '<rect x="0" y="0" width="50" height="50" rx="' + BIG_NUM_RX + '" fill="' + fill + '"/>' +
+          '<text x="25" y="' + (25 + fs * 0.34).toFixed(1) + '" text-anchor="middle" font-family="system-ui, sans-serif" font-size="' + fs + '" font-weight="800" fill="' + fg + '">' + text + '</text>' +
+          '</svg>';
+        return "data:image/svg+xml," + encodeURIComponent(svg);
+      });
     }
 
     // Reuses the fetched base template; replaces its __COLOR__ token (and,
     // for scale/translate effects, wraps the whale in a <g transform>).
     function frameUri(fill, effect, t, speed) {
       if (!BASE) return null;
+      if (effect === "static") {
+        // No time component: one URI per color for the life of the tab.
+        return cachedUri("w", fill, function () { return "data:image/svg+xml," + encodeURIComponent(BASE.replace(RE, fill)); });
+      }
       var inner = BASE.replace(RE, fill);
       if (effect === "heartbeat" || effect === "bounce") {
         var gattr = "";
@@ -314,7 +417,12 @@ const INJECTED_SCRIPT = `
       // requestAnimationFrame in hidden tabs, so a background tab would freeze
       // on the last frame: repaint here instead — animated states get a
       // wall-clock frame (coarse ~1 Hz animation), static states repaint
-      // (self-heal / pick up changes that happened while hidden).
+      // (self-heal / pick up changes that happened while hidden). A state
+      // change that happens while the tab is away (like the done hold
+      // expiring) paints on the next poll; the visibilitychange listener at
+      // the bottom fetches immediately when the tab comes back to the
+      // foreground, so that revert shows at once instead of waiting for a
+      // background-throttled tick.
       if (BASE && state + "|" + ACTIVE === PREV_KEY) {
         if (isStatic(state)) {
           var sframe = frameAt(state, 0);
@@ -327,8 +435,12 @@ const INJECTED_SCRIPT = `
       }
       PREV_KEY = state + "|" + ACTIVE;
       stopAnim();
-      if (!BASE) { // base.svg not loaded yet — fetch once, then start
-        fetch(location.origin + BASE_PATH + "?t=" + Date.now(), { cache: "no-store" })
+      // The count block is drawn from scratch, so it needs no base.svg: only the
+      // whale path waits for the template. Loading it here (and retrying on the
+      // next poll, since PREV_KEY was already set) keeps a failed/timed-out
+      // template fetch from blanking the tab while agents are busy.
+      if (!BASE && ACTIVE < BIG_NUM_MIN) {
+        timedFetch(location.origin + BASE_PATH + "?t=" + Date.now(), { cache: "no-store" })
           .then(function (r) { if (!r.ok) throw new Error("base " + r.status); return r.text(); })
           .then(function (txt) { BASE = txt; PREV_KEY = null; apply(state); })
           .catch(function () {});
@@ -370,7 +482,7 @@ const INJECTED_SCRIPT = `
       PREV_KEY = null; // force a full repaint on the next apply
     }
     function poll() {
-      fetch(location.origin + STATUS_PATH, { cache: "no-store" })
+      timedFetch(location.origin + STATUS_PATH, { cache: "no-store" })
         .then(function (r) { if (!r.ok) throw new Error("bad"); return r.json(); })
         .then(function (j) {
           syncCfg(j);
@@ -379,16 +491,35 @@ const INJECTED_SCRIPT = `
           // known count (initial 0 → whale only).
           if (typeof j.active === "number") ACTIVE = j.active;
           apply(j.state || "idle");
+          FAILED = false; // back online — the next outage may restore again
         })
-        // Transient failures (host restarting, network blip) must NOT kill the
-        // poll: restore the original icon and retry on the next tick. The SPA
-        // reconnects in place, so the tab survives a host restart — the icon
-        // has to come back on its own once the endpoint returns.
-        .catch(function () { stopAnim(); restore(); });
+        // Transient failures (host stopped/restarting, network blip) must NOT
+        // kill the poll: swap the shell's own icon back in ONCE per outage via
+        // the offline-safe restore() and keep retrying every tick. The SPA
+        // reconnects in place, so the live icon returns by itself once the
+        // endpoint answers again. restore() only ever writes data: URIs —
+        // never the original server URL, which is unreachable exactly while
+        // the host is down — so the tab cannot lose its icon mid-outage.
+        .catch(function () {
+          stopAnim();
+          if (FAILED) return; // already restored for this outage
+          FAILED = true;
+          restore();
+        });
     }
     captureOriginal();
     TIMER = setInterval(poll, 1000);
     poll();
+    // A BACKGROUND tab's timers are throttled (Chrome clamps setInterval to
+    // ~1/min after ~5 min hidden) and rAF is paused, so a state change that
+    // happened while the tab was away may take a while to reach the favicon —
+    // e.g. the green "done" frame sits there until the next poll finally fires.
+    // The moment the tab becomes visible again, fetch the fresh status and
+    // repaint right away instead of waiting for the next (possibly throttled)
+    // poll tick. Cheap, idempotent, and it also covers browsers that froze the
+    // page entirely while hidden (their first task on unfreeze is this poll).
+    function onVisible() { if (document.visibilityState === "visible") poll(); }
+    window.addEventListener("visibilitychange", onVisible);
     window.addEventListener("beforeunload", function () { stopAnim(); if (TIMER) clearInterval(TIMER); restore(); });
   } catch (e) { }
 })();
@@ -405,19 +536,178 @@ function resolveIconsDir(configured) {
   return join(__dirname, "..", "icons");
 }
 
+// ---- Color math for the default-color similarity check ---------------------
+// lib/client.js carries its OWN copy of this block: the two halves run in
+// different processes, there is no shared module and no build step (docs/main.js
+// already duplicates the same color math for the showcase site). Keep the
+// thresholds in sync when tuning either copy.
+/** Accepted defaultColor shape: `#rgb` or `#rrggbb` (case-insensitive). */
+const DEFAULT_COLOR_RX = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
+/** CIE76 ΔE below which two colors are practically the same. */
+const SIMILAR_DE_STRONG = 12;
+/** CIE76 ΔE below which two colors are easily confused at favicon size. */
+const SIMILAR_DE_WARN = 25;
+/** Lab chroma above which a default color collides with a rainbow sweep. */
+const RAINBOW_CHROMA_MIN = 15;
+/** The states a default color is compared against (idle is the default itself). */
+const OTHER_STATES = STATE_NAMES.filter((name) => name !== "idle");
+
+/** `#rgb` / `#rrggbb` → lowercase 6-digit hex, or null when malformed. */
+function normalizeHex(value) {
+  if (typeof value !== "string") return null;
+  const text = value.trim();
+  if (!DEFAULT_COLOR_RX.test(text)) return null;
+  const body = text.slice(1).toLowerCase();
+  return body.length === 3
+    ? "#" + body[0] + body[0] + body[1] + body[1] + body[2] + body[2]
+    : "#" + body;
+}
+
+function hexToRgb(hex) {
+  let body = String(hex).replace("#", "");
+  // Expand #rgb exactly like the browser half does — every host caller feeds
+  // normalizeHex()'s 6-digit output today, but the shortcut is a trap for the
+  // next caller (and this copy must stay equivalent to lib/client.js's).
+  if (body.length === 3) body = body[0] + body[0] + body[1] + body[1] + body[2] + body[2];
+  const n = parseInt(body, 16);
+  return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+}
+
+function rgbToHex(r, g, b) {
+  return "#" + [r, g, b].map((v) => {
+    const c = Math.max(0, Math.min(255, Math.round(v)));
+    return ("0" + c.toString(16)).slice(-2);
+  }).join("");
+}
+
+/** Linear blend between two hex colors (mirrors the browser's `mix()`). */
+function mixHex(a, b, t) {
+  const ca = hexToRgb(a);
+  const cb = hexToRgb(b);
+  return rgbToHex(ca[0] + (cb[0] - ca[0]) * t, ca[1] + (cb[1] - ca[1]) * t, ca[2] + (cb[2] - ca[2]) * t);
+}
+
+/** CIELAB (D65) for an sRGB hex color. */
+function labOf(hex) {
+  const rgb = hexToRgb(hex);
+  const lin = (v) => {
+    const c = v / 255;
+    return c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+  };
+  const r = lin(rgb[0]);
+  const g = lin(rgb[1]);
+  const b = lin(rgb[2]);
+  const x = (0.4124564 * r + 0.3575761 * g + 0.1804375 * b) / 0.95047;
+  const y = 0.2126729 * r + 0.7151522 * g + 0.072175 * b;
+  const z = (0.0193339 * r + 0.119192 * g + 0.9503041 * b) / 1.08883;
+  const f = (t) => (t > 216 / 24389 ? Math.cbrt(t) : (841 / 108) * t + 4 / 29);
+  const fx = f(x);
+  const fy = f(y);
+  const fz = f(z);
+  return [116 * fy - 16, 500 * (fx - fy), 200 * (fy - fz)];
+}
+
+/** CIE76 ΔE (Euclidean distance in CIELAB). */
+function deltaE(a, b) {
+  const la = labOf(a);
+  const lb = labOf(b);
+  return Math.sqrt(
+    Math.pow(la[0] - lb[0], 2) + Math.pow(la[1] - lb[1], 2) + Math.pow(la[2] - lb[2], 2)
+  );
+}
+
+function labChroma(hex) {
+  const l = labOf(hex);
+  return Math.sqrt(l[1] * l[1] + l[2] * l[2]);
+}
+
+/**
+ * The fills a state actually paints, mirroring the browser's `frameColor()`:
+ * `blink` toggles colors[0] ⇄ colors[1] (a darker second color is derived when
+ * colors[1] is omitted), `breath` interpolates between them, everything else
+ * uses colors[0]. `rainbow` is flagged instead — it sweeps every hue.
+ */
+function stateFills(state) {
+  const cols = Array.isArray(state?.colors) ? state.colors : [];
+  const effect = state?.effect || "static";
+  const c0 = normalizeHex(cols[0] || "");
+  const rainbow = effect === "rainbow";
+  // A rainbow state never paints its own colors[0] literally (that value is
+  // only the starting hue — the sweep covers the whole wheel), so it has no
+  // comparable fills: the chroma rule in colorWarnings() covers it instead.
+  if (!c0 || rainbow) return { fills: [], rainbow };
+  const c1 = normalizeHex(cols[1] || "") || mixHex(c0, "#000000", 0.35);
+  if (effect === "blink") return { fills: [c0, c1], rainbow: false };
+  if (effect === "breath") {
+    // The browser paints the CONTINUOUS mix, so a sparse sample can only ever
+    // over-estimate the distance: a blue->green breath was reported ΔE 37 away
+    // from a default colour it actually passes through (ΔE 0). 33 samples keep
+    // the worst reported-vs-true gap around 5 ΔE (see lib/client.js's copy).
+    const fills = [];
+    for (let i = 0; i <= 32; i += 1) fills.push(mixHex(c0, c1, i / 32));
+    return { fills, rainbow: false };
+  }
+  return { fills: [c0], rainbow };
+}
+
+/**
+ * Similarity warnings for the effective default color (the idle primary).
+ * Only the default is compared against the other states — NOT the states
+ * against each other: the shipped defaults deliberately share #FACC15 between
+ * `running` and the `asking` blink, so a pairwise check would warn forever.
+ */
+function colorWarnings(states) {
+  const warnings = [];
+  const base = normalizeHex(states?.idle?.colors?.[0] || "");
+  if (!base) return warnings;
+  // Idle itself on `rainbow` (composition entry / hand-written settings.yaml —
+  // the card never exposes it): the idle icon sweeps every hue, so the default
+  // colour can never stay distinguishable from it. One advisory replaces the
+  // pairwise pass, which would judge a colour idle never paints literally.
+  if ((states?.idle?.effect || "static") === "rainbow") {
+    if (labChroma(base) >= RAINBOW_CHROMA_MIN) {
+      warnings.push({ code: "rainbow-overlap", state: "idle", base, level: "warn" });
+    }
+    return warnings;
+  }
+  for (const name of OTHER_STATES) {
+    const { fills, rainbow } = stateFills(states?.[name]);
+    if (rainbow && labChroma(base) >= RAINBOW_CHROMA_MIN) {
+      warnings.push({ code: "rainbow-overlap", state: name, base, level: "warn" });
+    }
+    let closest = null;
+    for (const fill of fills) {
+      const de = deltaE(base, fill);
+      if (closest === null || de < closest.deltaE) closest = { color: fill, deltaE: de };
+    }
+    if (closest && closest.deltaE < SIMILAR_DE_WARN) {
+      warnings.push({
+        code: "color-too-close",
+        state: name,
+        base,
+        color: closest.color,
+        deltaE: Math.round(closest.deltaE * 10) / 10,
+        level: closest.deltaE < SIMILAR_DE_STRONG ? "strong" : "warn",
+      });
+    }
+  }
+  return warnings;
+}
+
 /**
  * Cordis plugin entry. Returns the standard `{ apply, inject, config }`
  * shape so the host composition can mount it once at startup.
  */
 export default {
   name: "dsh-web-icon-indicator",
-  inject: ["webServer", "timer", "agents", "fs", "sandboxPolicy"],
+  inject: ["webServer", "timer", "agents", "fs"],
   config: {
     askingHoldMs: DEFAULTS.askingHoldMs,
     doneHoldMs: DEFAULTS.doneHoldMs,
     statusPath: DEFAULTS.statusPath,
     iconPathPrefix: DEFAULTS.iconPathPrefix,
     iconsDir: undefined,
+    defaultColor: undefined,
     states: DEFAULTS.states,
   },
   /** Settings namespace + validation schema (exported for reuse/tooling). */
@@ -438,6 +728,7 @@ export default {
     // normalization when the profile composes no settings service.
     const resolveConfig = (raw) => {
       const stateConfigs = {};
+      const warnings = [];
       for (const name of STATE_NAMES) {
         const merged = { ...(DEFAULTS.states[name] || {}), ...(raw.states?.[name] || {}) };
         // Guard against unknown effect names: fall back to "static" so the
@@ -448,15 +739,75 @@ export default {
         let cols = merged.colors;
         if (typeof cols === "string") cols = [cols];
         if (!Array.isArray(cols)) cols = [];
-        cols = cols.filter((c) => typeof c === "string" && /^#[0-9a-fA-F]{3,6}$/.test(c.trim()));
+        // Strict `#rgb` / `#rrggbb` only — the same rule normalizeHex() and the
+        // card use. The old lenient 3-6 digit test let a "#1234" through and
+        // parseInt() painted a bogus colour from it, which the card (correctly)
+        // refused to reason about.
+        cols = cols.filter((c) => typeof c === "string" && DEFAULT_COLOR_RX.test(c.trim()));
         merged.colors = cols.length ? cols : [...(DEFAULTS.states[name]?.colors || ["#1a1a1a"])];
         // speed: must be a positive number; otherwise use the default (1200).
         if (typeof merged.speed !== "number" || !(merged.speed > 0)) delete merged.speed;
         stateConfigs[name] = merged;
       }
-      return { ...DEFAULTS, ...raw, states: stateConfigs };
+      // `undefined` values must not shadow a DEFAULTS entry: the plugin's own
+      // static `config` row carries `iconsDir: undefined` by design, and a
+      // schema-resolved settings value may omit optional keys entirely. Only
+      // keys the caller actually set may override a default.
+      const defined = {};
+      for (const [key, value] of Object.entries(raw || {})) {
+        if (value !== undefined) defined[key] = value;
+      }
+      const resolved = { ...DEFAULTS, ...defined, states: stateConfigs };
+      // `defaultColor` is sugar for the idle state's PRIMARY color. Fold it into
+      // `states.idle.colors[0]` here instead of teaching the browser a second
+      // rendering path: the injected script, the baked `__CFG__` payload and
+      // even an already-baked older bundle therefore keep working unchanged,
+      // and the live settings sync (`cfg.states = next.states`) carries it for
+      // free. A malformed value is dropped with a warning, never painted.
+      delete resolved.defaultColor;
+      const requestedDefault = typeof defined.defaultColor === "string"
+        ? defined.defaultColor.trim()
+        : defined.defaultColor;
+      // "" / whitespace written by hand into the composition entry means "not
+      // set" — not a malformed color to warn about. Neither does an empty YAML
+      // value, which parses as null (`defaultColor:`).
+      if (requestedDefault != null && requestedDefault !== "") {
+        const normalized = normalizeHex(requestedDefault);
+        if (normalized) {
+          const idle = stateConfigs.idle;
+          stateConfigs.idle = { ...idle, colors: [normalized, ...(idle.colors || []).slice(1)] };
+          resolved.defaultColor = normalized;
+        } else {
+          warnings.push({ code: "invalid-color", value: String(requestedDefault) });
+        }
+      }
+      warnings.push(...colorWarnings(stateConfigs));
+      resolved.warnings = warnings;
+      return resolved;
+    };
+    // Surface the similarity / validity warnings on the host as well: the
+    // settings card computes its own live copy, while this covers configs that
+    // arrive through the composition entry (a hand-written cordis.yml) and
+    // leaves a server-side record. `ctx.logger` is cordis' core logging
+    // service — guard it, since the zero-dep test harness drives `apply()`
+    // with a ctx that has none.
+    const logWarnings = (list) => {
+      if (!Array.isArray(list) || list.length === 0) return;
+      try {
+        if (typeof ctx.logger !== "function") return;
+        const logger = ctx.logger("dsh-web-icon-indicator");
+        for (const w of list) {
+          const text = w.code === "invalid-color"
+            ? `defaultColor ${JSON.stringify(w.value)} is not a 3- or 6-digit hex color — ignored`
+            : w.code === "rainbow-overlap"
+              ? `defaultColor ${w.base} is too close to the "${w.state}" state: its rainbow effect sweeps every hue`
+              : `defaultColor ${w.base} is ${w.level === "strong" ? "nearly identical to" : "too close to"} the "${w.state}" state color ${w.color} (ΔE ${w.deltaE})`;
+          if (logger && typeof logger.warn === "function") logger.warn(text);
+        }
+      } catch (e) {}
     };
     let cfg = resolveConfig(entry);
+    logWarnings(cfg.warnings);
     // The injected script bakes config at injection time; rebuild it whenever
     // the settings section changes so the NEXT page load picks the new values
     // up (reload the tab — same contract as before this registration).
@@ -483,24 +834,30 @@ export default {
           // Settings service mounted, or the section changed: re-resolve, then
           // mutate cfg in place so the state-machine closures (asking/done hold)
           // and the injected script see the new values immediately.
+          // `statusPath` / `iconPathPrefix` are NOT taken from the settings
+          // source: they are baked into the route table and the injected script
+          // at registration time, so honoring a settings edit here would break
+          // the live poll (see CONFIG_SCHEMA).
           const next = resolveConfig(source());
           cfg.askingHoldMs = next.askingHoldMs;
           cfg.doneHoldMs = next.doneHoldMs;
-          cfg.statusPath = next.statusPath;
-          cfg.iconPathPrefix = next.iconPathPrefix;
           if (next.iconsDir !== undefined) cfg.iconsDir = next.iconsDir;
           cfg.states = next.states;
+          // `defaultColor` / `warnings` ride along with `states`: the color is
+          // already folded into `states.idle.colors[0]`, so the browser needs no
+          // new key — they are kept for observability (status echo + log).
+          cfg.defaultColor = next.defaultColor;
+          cfg.warnings = next.warnings;
           iconsDir = resolveIconsDir(cfg.iconsDir);
           script = buildScript(cfg);
+          logWarnings(cfg.warnings);
         },
       });
     });
     const webServer = ctx.webServer;
     const agents = ctx.agents;
     const fs = ctx.fs;
-    const sp = ctx.sandboxPolicy;
     const lastSeen = new Map();
-    void sp; // sandboxPolicy injection is currently unused — reserved for future file-access policy
 
     // -- State machine -------------------------------------------------------
     const states = new Map();        // agentId -> { state, since }
@@ -572,31 +929,46 @@ export default {
     // leaves `running`, so a lost `tools/result` cannot pin `asking` forever.
     const scheduleAskCheck = (id) => {
       const prevHandle = askTimers.get(id);
-      if (prevHandle) { try { prevHandle(); } catch (e) {} askTimers.delete(id); }
+      // Never cancel a handle whose callback is executing right now: it is the
+      // very call re-arming the pin, and its `finally` would then delete the
+      // fresh handle and leave the session pinned to `asking` with no timer to
+      // release it. A stale (non-running) handle is still cancelled, so a
+      // repeated pre-execute cannot stack two timers.
+      if (prevHandle && !prevHandle.running()) {
+        try { prevHandle(); } catch (e) {}
+        askTimers.delete(id);
+      }
+      let running = false;
       const handle = ctx.timer.timeout(() => {
+        running = true;
         askTimers.delete(id);
-        if (!asking.has(id)) return;
-        if (!askDone.has(id)) {
-          const live = agents.get(id);
-          // Result not yet reported AND the agent is still mid-turn: the user
-          // may still be deciding — keep the pin (no re-arm budget; a human
-          // question can legitimately outlast many hold windows).
-          if (live && live.status === "running") { scheduleAskCheck(id); return; }
-          // Result never arrived and the turn ended (agent idle / gone): a lost
-          // tools/result cannot keep the icon blinking forever — force-release
-          // the pin against live status.
+        try {
+          if (!asking.has(id)) return;
+          if (!askDone.has(id)) {
+            const live = agents.get(id);
+            // Result not yet reported AND the agent is still mid-turn: the user
+            // may still be deciding — keep the pin (no re-arm budget; a human
+            // question can legitimately outlast many hold windows).
+            if (live && live.status === "running") { scheduleAskCheck(id); return; }
+            // Result never arrived and the turn ended (agent idle / gone): a lost
+            // tools/result cannot keep the icon blinking forever — force-release
+            // the pin against live status.
+            asking.delete(id);
+            askDone.delete(id);
+            if (live) setState(id, live.status === "running" ? "running" : "idle");
+            else setState(id, "idle");
+            return;
+          }
           asking.delete(id);
           askDone.delete(id);
+          const live = agents.get(id);
           if (live) setState(id, live.status === "running" ? "running" : "idle");
           else setState(id, "idle");
-          return;
+        } finally {
+          running = false;
         }
-        asking.delete(id);
-        askDone.delete(id);
-        const live = agents.get(id);
-        if (live) setState(id, live.status === "running" ? "running" : "idle");
-        else setState(id, "idle");
       }, cfg.askingHoldMs);
+      handle.running = () => running;
       askTimers.set(id, handle);
     };
 
@@ -648,6 +1020,7 @@ export default {
       asking.delete(id);
       askDone.delete(id);
       pendingApprovals.delete(id);
+      approvalCursor.delete(id);
       lastSeen.delete(id);
       cancelDoneHold(id);
       const t = askTimers.get(id);
@@ -659,17 +1032,34 @@ export default {
     // 0.1.2-alpha.4 `Session.events` is gone — read the log on demand through
     // `session.snapshotEvents()` (a frozen half-open range snapshot). Guard on
     // the method so older/newer hosts degrade gracefully.
+    //
+    // The fold is INCREMENTAL: `snapshotEvents()` deep-freezes every event it
+    // returns, and reconcile runs on every 1 s status poll, so re-reading the
+    // whole log per poll would clone the entire history each second. A per-agent
+    // cursor keeps only the delta (the log is append-only, so the open-approval
+    // set is a pure fold over the events seen so far).
+    const approvalCursor = new Map(); // agentId -> { seq, open: Set<approvalId> }
     const hasPendingApproval = (live) => {
       const session = live?.session;
       if (!session || typeof session.snapshotEvents !== "function") return false;
-      const events = session.snapshotEvents();
-      if (!Array.isArray(events)) return false;
-      const open = new Set();
+      const id = live?.id ?? null;
+      const cursor = (id != null && approvalCursor.get(id)) || { seq: 0, open: new Set() };
+      let events;
+      try {
+        events = session.snapshotEvents(cursor.seq);
+      } catch (e) {
+        return cursor.open.size > 0; // keep the last good fold on a read failure
+      }
+      if (!Array.isArray(events)) return cursor.open.size > 0;
+      let seq = cursor.seq;
       for (const ev of events) {
-        if (ev.type === "approval/asked") open.add(ev.data?.id);
-        else if (ev.type === "approval/decided") open.delete(ev.data?.id);
+        if (typeof ev?.seq === "number" && ev.seq >= seq) seq = ev.seq + 1;
+        if (ev?.type === "approval/asked") cursor.open.add(ev.data?.id);
+        else if (ev?.type === "approval/decided") cursor.open.delete(ev.data?.id);
       }
-      return open.size > 0;
+      cursor.seq = seq;
+      if (id != null) approvalCursor.set(id, cursor);
+      return cursor.open.size > 0;
     };
 
     // Reconcile running->idle transitions on every status request.
@@ -741,7 +1131,16 @@ export default {
         res.statusCode = 200;
         res.setHeader("Content-Type", "application/json; charset=utf-8");
         res.setHeader("Cache-Control", "no-store");
-        res.end(JSON.stringify({ ...aggregate(), states: cfg.states }));
+        // `defaultColor` + `warnings` are additive: older browser bundles ignore
+        // unknown keys, and the live config sync only reads `states`.
+        // `defaultColor` is echoed as null when none is configured so the
+        // documented shape has the key unconditionally.
+        res.end(JSON.stringify({
+          ...aggregate(),
+          states: cfg.states,
+          defaultColor: cfg.defaultColor ?? null,
+          warnings: cfg.warnings || [],
+        }));
       },
     }));