@hellcoder/companion 0.116.0 → 0.116.1-preview.20260814041931.d191f06

package/server/magic-ui-ops.test.ts

@@ -0,0 +1,239 @@
+// Tests for MagicUI op parsing, validation/sanitization and state reduction.
+//
+// The watcher model's output is untrusted: these tests pin down that
+// (a) replies parse leniently (fenced/bare/prose-wrapped JSON) but fail
+//     closed on garbage,
+// (b) HTML is sanitized to an inert allowlist (no scripts, handlers,
+//     inline styles or URLs — the iframe sandbox is the second layer),
+// (c) budgets (ops/slots/log lengths) are enforced in the reducer, and
+// (d) reduction is pure, version-bumping, and never mutates its input.
+import { describe, expect, it } from "vitest";
+import {
+  appendDecision,
+  applyOps,
+  makeDecisionEntry,
+  parseMagicUiReply,
+  sanitizeMagicHtml,
+  validateOps,
+} from "./magic-ui-ops.js";
+import {
+  MAGIC_UI_MAX_DECISIONS,
+  MAGIC_UI_MAX_OPS_PER_TURN,
+  MAGIC_UI_MAX_SLOTS,
+  emptyMagicUiState,
+  type MagicUiOp,
+} from "./magic-ui-types.js";
+
+const NOW = 1_750_000_000_000;
+
+describe("parseMagicUiReply", () => {
+  it("parses a fenced json block", () => {
+    const reply = 'Here you go:\n```json\n[{"op":"remove_slot","slot":"a"}]\n```';
+    expect(parseMagicUiReply(reply)).toEqual([{ op: "remove_slot", slot: "a" }]);
+  });
+
+  it("parses a bare JSON array", () => {
+    expect(parseMagicUiReply('[{"op":"remove_slot","slot":"a"}]')).toEqual([
+      { op: "remove_slot", slot: "a" },
+    ]);
+  });
+
+  it("recovers an array embedded in prose", () => {
+    expect(parseMagicUiReply('sure! [{"op":"remove_slot","slot":"a"}] done')).toEqual([
+      { op: "remove_slot", slot: "a" },
+    ]);
+  });
+
+  it("returns [] for an empty reply (nothing to do)", () => {
+    expect(parseMagicUiReply("   ")).toEqual([]);
+  });
+
+  it("returns null for unparseable replies", () => {
+    expect(parseMagicUiReply("no ops here")).toBeNull();
+    expect(parseMagicUiReply('[{"op": broken]')).toBeNull();
+    expect(parseMagicUiReply('{"op":"set_slot"}')).toBeNull();
+  });
+});
+
+describe("sanitizeMagicHtml", () => {
+  it("strips script tags and event handlers", () => {
+    const dirty = '<div onclick="evil()"><script>alert(1)</script><p>ok</p></div>';
+    const clean = sanitizeMagicHtml(dirty);
+    expect(clean).not.toContain("script");
+    expect(clean).not.toContain("onclick");
+    expect(clean).toContain("<p>ok</p>");
+  });
+
+  it("strips inline styles, links and images", () => {
+    const dirty = '<p style="position:fixed">x</p><a href="javascript:evil()">y</a><img src="http://x/t.png">';
+    const clean = sanitizeMagicHtml(dirty);
+    expect(clean).not.toContain("style=");
+    expect(clean).not.toContain("href");
+    expect(clean).not.toContain("img");
+  });
+
+  it("keeps allowlisted structure with classes", () => {
+    const html = '<div class="stat-grid"><h3>Files</h3><ul><li>a.ts</li></ul></div>';
+    expect(sanitizeMagicHtml(html)).toBe(html);
+  });
+});
+
+describe("validateOps", () => {
+  it("drops unknown and malformed ops, keeps valid ones", () => {
+    const ops = validateOps([
+      { op: "hack_the_planet" },
+      { op: "set_slot" }, // missing fields
+      { op: "set_slot", slot: "progress", html: "<p>hi</p>" },
+      null,
+      42,
+    ]);
+    expect(ops).toEqual([
+      { op: "set_slot", slot: "progress", html: "<p>hi</p>", title: undefined, area: undefined, span: undefined },
+    ]);
+  });
+
+  it("sanitizes set_slot html", () => {
+    const ops = validateOps([
+      { op: "set_slot", slot: "x", html: '<script>a</script><b onmouseover="p()">t</b>' },
+    ]);
+    expect(ops).toHaveLength(1);
+    const op = ops[0] as Extract<MagicUiOp, { op: "set_slot" }>;
+    expect(op.html).toBe("<b>t</b>");
+  });
+
+  it("drops a set_slot whose html sanitizes to nothing", () => {
+    expect(validateOps([{ op: "set_slot", slot: "x", html: "<script>a</script>" }])).toEqual([]);
+  });
+
+  it("caps the number of ops per turn", () => {
+    const raw = Array.from({ length: MAGIC_UI_MAX_OPS_PER_TURN + 10 }, (_, i) => ({
+      op: "remove_slot",
+      slot: `s${i}`,
+    }));
+    expect(validateOps(raw)).toHaveLength(MAGIC_UI_MAX_OPS_PER_TURN);
+  });
+
+  it("validates chart specs and drops non-numeric data", () => {
+    const ops = validateOps([
+      { op: "chart", slot: "c", spec: { kind: "bar", series: [{ label: "tests", data: [1, "x", 3] }] } },
+      { op: "chart", slot: "bad", spec: { kind: "pie3d", series: [{ label: "a", data: [1] }] } },
+      { op: "chart", slot: "bad2", spec: { kind: "bar", series: [] } },
+    ]);
+    expect(ops).toHaveLength(1);
+    const chart = ops[0] as Extract<MagicUiOp, { op: "chart" }>;
+    expect(chart.spec.series[0].data).toEqual([1, 3]);
+  });
+
+  it("normalizes open_item kinds and validates snippet/stat/decision ops", () => {
+    const ops = validateOps([
+      { op: "open_item", id: "run-tests", text: "Run the migration script", kind: "weird" },
+      { op: "resolve_item", id: "run-tests" },
+      { op: "snippet", slot: "s", title: "Migrate DB", code: "bun run migrate", language: "bash" },
+      { op: "stat", slot: "t", label: "Tests", value: "34 pass", trend: "up" },
+      { op: "decision_log", title: "Chose approach B", detail: "Simpler rollback path" },
+      { op: "session_summary", text: "We did things." },
+    ]);
+    expect(ops.map((o) => o.op)).toEqual([
+      "open_item", "resolve_item", "snippet", "stat", "decision_log", "session_summary",
+    ]);
+    expect((ops[0] as Extract<MagicUiOp, { op: "open_item" }>).kind).toBe("action");
+  });
+});
+
+describe("applyOps", () => {
+  it("sets slots, bumps version, and does not mutate the input state", () => {
+    const state = emptyMagicUiState(NOW);
+    const ops = validateOps([
+      { op: "set_slot", slot: "hero", html: "<p>Working on auth</p>", area: "hero" },
+      { op: "stat", slot: "tests", label: "Tests", value: "34", area: "side" },
+    ]);
+    const next = applyOps(state, ops, NOW + 1);
+    expect(next.version).toBe(1);
+    expect(next.slots.hero?.html).toBe("<p>Working on auth</p>");
+    expect(next.slots.tests?.stat?.value).toBe("34");
+    expect(next.layout).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ slot: "hero", area: "hero" }),
+        expect.objectContaining({ slot: "tests", area: "side" }),
+      ]),
+    );
+    // Purity: original untouched
+    expect(state.version).toBe(0);
+    expect(Object.keys(state.slots)).toHaveLength(0);
+  });
+
+  it("removes slots together with their layout entries", () => {
+    let state = applyOps(
+      emptyMagicUiState(NOW),
+      validateOps([{ op: "set_slot", slot: "a", html: "<p>x</p>", area: "main" }]),
+      NOW,
+    );
+    state = applyOps(state, validateOps([{ op: "remove_slot", slot: "a" }]), NOW + 1);
+    expect(state.slots.a).toBeUndefined();
+    expect(state.layout.find((l) => l.slot === "a")).toBeUndefined();
+    expect(state.version).toBe(2);
+  });
+
+  it("adds, dedupes and resolves open items", () => {
+    let state = applyOps(
+      emptyMagicUiState(NOW),
+      validateOps([
+        { op: "open_item", id: "q1", text: "Which DB?", kind: "question" },
+        { op: "open_item", id: "a1", text: "Run bun run migrate", kind: "action" },
+      ]),
+      NOW,
+    );
+    expect(state.openItems.map((i) => i.id)).toEqual(["a1", "q1"]);
+    // Re-adding the same id replaces it instead of duplicating
+    state = applyOps(state, validateOps([{ op: "open_item", id: "q1", text: "Which DB? (updated)", kind: "question" }]), NOW + 1);
+    expect(state.openItems.filter((i) => i.id === "q1")).toHaveLength(1);
+    expect(state.openItems.find((i) => i.id === "q1")?.text).toContain("updated");
+    state = applyOps(state, validateOps([{ op: "resolve_item", id: "q1" }]), NOW + 2);
+    expect(state.openItems.map((i) => i.id)).toEqual(["a1"]);
+  });
+
+  it("caps the decision log", () => {
+    let state = emptyMagicUiState(NOW);
+    for (let i = 0; i < MAGIC_UI_MAX_DECISIONS + 5; i++) {
+      state = applyOps(state, validateOps([{ op: "decision_log", title: `d${i}`, detail: "x" }]), NOW + i);
+    }
+    expect(state.decisionLog).toHaveLength(MAGIC_UI_MAX_DECISIONS);
+    // Newest first
+    expect(state.decisionLog[0].title).toBe(`d${MAGIC_UI_MAX_DECISIONS + 4}`);
+  });
+
+  it("evicts the oldest slots beyond the slot budget", () => {
+    let state = emptyMagicUiState(NOW);
+    for (let i = 0; i < MAGIC_UI_MAX_SLOTS + 3; i++) {
+      state = applyOps(state, validateOps([{ op: "set_slot", slot: `s${i}`, html: `<p>${i}</p>` }]), NOW + i);
+    }
+    expect(Object.keys(state.slots)).toHaveLength(MAGIC_UI_MAX_SLOTS);
+    expect(state.slots.s0).toBeUndefined();
+    expect(state.slots[`s${MAGIC_UI_MAX_SLOTS + 2}`]).toBeDefined();
+  });
+
+  it("stores the session summary without rendering slots", () => {
+    const state = applyOps(
+      emptyMagicUiState(NOW),
+      validateOps([{ op: "session_summary", text: "Auth refactor session." }]),
+      NOW,
+    );
+    expect(state.sessionSummary).toBe("Auth refactor session.");
+    expect(Object.keys(state.slots)).toHaveLength(0);
+  });
+});
+
+describe("appendDecision", () => {
+  it("prepends server-generated entries and bumps the version", () => {
+    const state = emptyMagicUiState(NOW);
+    const entry = makeDecisionEntry("user", "Bash", "Allowed: rm -rf dist", NOW + 5, "allow");
+    const next = appendDecision(state, entry);
+    expect(next.decisionLog[0]).toMatchObject({
+      source: "user",
+      title: "Bash",
+      behavior: "allow",
+    });
+    expect(next.version).toBe(1);
+    expect(state.decisionLog).toHaveLength(0);
+  });
+});

package/server/magic-ui-ops.ts

@@ -0,0 +1,365 @@
+// ─── MagicUI op parsing / validation / reduction ─────────────────────────────
+//
+// The watcher model replies with a single JSON array of patch ops. This
+// module turns that untrusted text into a validated, sanitized op list and
+// folds it into the canonical MagicUiDashboardState.
+//
+// Defense in depth: the browser renders watcher HTML only inside a sandboxed
+// opaque-origin iframe with a no-network CSP — the sanitizer here is the
+// second belt, keeping scripts/handlers/URLs out of persisted state at the
+// source so replays and future render surfaces stay safe too.
+
+import sanitizeHtmlLib from "sanitize-html";
+import {
+  MAGIC_UI_MAX_CHART_POINTS,
+  MAGIC_UI_MAX_CHART_SERIES,
+  MAGIC_UI_MAX_DECISIONS,
+  MAGIC_UI_MAX_HTML_CHARS,
+  MAGIC_UI_MAX_OPEN_ITEMS,
+  MAGIC_UI_MAX_OPS_PER_TURN,
+  MAGIC_UI_MAX_SLOTS,
+  MAGIC_UI_MAX_SNIPPET_CHARS,
+  type MagicChartSpec,
+  type MagicUiArea,
+  type MagicUiDashboardState,
+  type MagicUiDecisionEntry,
+  type MagicUiLayoutEntry,
+  type MagicUiOp,
+} from "./magic-ui-types.js";
+
+const AREAS: ReadonlySet<string> = new Set(["hero", "main", "side", "footer"]);
+const CHART_KINDS: ReadonlySet<string> = new Set(["bar", "line", "donut", "sparkline"]);
+const OPEN_ITEM_KINDS: ReadonlySet<string> = new Set(["action", "question", "blocker"]);
+
+const SANITIZE_OPTIONS: sanitizeHtmlLib.IOptions = {
+  allowedTags: [
+    "div", "span", "p", "h1", "h2", "h3", "h4", "ul", "ol", "li",
+    "table", "thead", "tbody", "tr", "td", "th",
+    "strong", "em", "b", "i", "u", "s", "code", "pre", "small", "br", "hr",
+    "blockquote", "progress", "mark", "kbd", "sub", "sup",
+  ],
+  allowedAttributes: {
+    "*": ["class", "data-*"],
+    progress: ["value", "max", "class"],
+  },
+  // No style attribute at all: class-based styling only (the runtime ships
+  // utility classes). Inline style is the classic sanitizer escape hatch.
+  allowedStyles: {},
+  disallowedTagsMode: "discard",
+  allowedSchemes: [],
+};
+
+export function sanitizeMagicHtml(html: string): string {
+  return sanitizeHtmlLib(html, SANITIZE_OPTIONS);
+}
+
+function isNonEmptyString(v: unknown, max = 512): v is string {
+  return typeof v === "string" && v.trim().length > 0 && v.length <= max;
+}
+
+function normalizeSpan(v: unknown): 1 | 2 | 3 | undefined {
+  return v === 1 || v === 2 || v === 3 ? v : undefined;
+}
+
+function normalizeArea(v: unknown): MagicUiArea | undefined {
+  return typeof v === "string" && AREAS.has(v) ? (v as MagicUiArea) : undefined;
+}
+
+function validateChartSpec(raw: unknown): MagicChartSpec | null {
+  if (!raw || typeof raw !== "object") return null;
+  const spec = raw as Record<string, unknown>;
+  if (typeof spec.kind !== "string" || !CHART_KINDS.has(spec.kind)) return null;
+  if (!Array.isArray(spec.series) || spec.series.length === 0) return null;
+  const series: MagicChartSpec["series"] = [];
+  for (const s of spec.series.slice(0, MAGIC_UI_MAX_CHART_SERIES)) {
+    if (!s || typeof s !== "object") return null;
+    const entry = s as Record<string, unknown>;
+    if (!Array.isArray(entry.data)) return null;
+    const data = entry.data
+      .slice(0, MAGIC_UI_MAX_CHART_POINTS)
+      .filter((n): n is number => typeof n === "number" && Number.isFinite(n));
+    if (data.length === 0) return null;
+    series.push({
+      label: isNonEmptyString(entry.label, 120) ? entry.label : "",
+      data,
+    });
+  }
+  if (series.length === 0) return null;
+  const labels = Array.isArray(spec.labels)
+    ? spec.labels
+      .slice(0, MAGIC_UI_MAX_CHART_POINTS)
+      .filter((l): l is string => typeof l === "string")
+      .map((l) => l.slice(0, 80))
+    : undefined;
+  return {
+    kind: spec.kind as MagicChartSpec["kind"],
+    title: isNonEmptyString(spec.title, 160) ? spec.title : undefined,
+    labels,
+    series,
+  };
+}
+
+function validateLayoutEntries(raw: unknown): MagicUiLayoutEntry[] | null {
+  if (!Array.isArray(raw)) return null;
+  const out: MagicUiLayoutEntry[] = [];
+  for (const e of raw.slice(0, MAGIC_UI_MAX_SLOTS)) {
+    if (!e || typeof e !== "object") continue;
+    const entry = e as Record<string, unknown>;
+    const area = normalizeArea(entry.area);
+    if (!isNonEmptyString(entry.slot, 80) || !area) continue;
+    out.push({ slot: entry.slot, area, span: normalizeSpan(entry.span) });
+  }
+  return out.length > 0 ? out : null;
+}
+
+/**
+ * Extract the ops array from a raw watcher reply. Accepts either a fenced
+ * ```json block (preferred; the prompt asks for exactly one) or a bare JSON
+ * array. Returns [] for "nothing to do" replies and null for unparseable
+ * ones (so callers can count consecutive failures).
+ */
+export function parseMagicUiReply(text: string): unknown[] | null {
+  const trimmed = text.trim();
+  if (!trimmed) return [];
+  const fence = /```(?:json)?\s*([\s\S]*?)```/.exec(trimmed);
+  const candidate = fence ? fence[1].trim() : trimmed;
+  const start = candidate.indexOf("[");
+  const end = candidate.lastIndexOf("]");
+  if (start === -1 || end === -1 || end < start) return null;
+  try {
+    const parsed = JSON.parse(candidate.slice(start, end + 1));
+    return Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Validate and sanitize raw parsed ops. Unknown / malformed ops are dropped
+ * (never fatal — a partially-usable turn still updates the dashboard).
+ */
+export function validateOps(raw: unknown[]): MagicUiOp[] {
+  const ops: MagicUiOp[] = [];
+  for (const item of raw.slice(0, MAGIC_UI_MAX_OPS_PER_TURN)) {
+    if (!item || typeof item !== "object") continue;
+    const o = item as Record<string, unknown>;
+    switch (o.op) {
+      case "set_slot": {
+        if (!isNonEmptyString(o.slot, 80) || typeof o.html !== "string") break;
+        const html = sanitizeMagicHtml(o.html.slice(0, MAGIC_UI_MAX_HTML_CHARS * 2)).slice(0, MAGIC_UI_MAX_HTML_CHARS);
+        if (!html.trim()) break;
+        ops.push({
+          op: "set_slot",
+          slot: o.slot,
+          html,
+          title: isNonEmptyString(o.title, 160) ? o.title : undefined,
+          area: normalizeArea(o.area),
+          span: normalizeSpan(o.span),
+        });
+        break;
+      }
+      case "remove_slot": {
+        if (isNonEmptyString(o.slot, 80)) ops.push({ op: "remove_slot", slot: o.slot });
+        break;
+      }
+      case "layout": {
+        const slots = validateLayoutEntries(o.slots);
+        if (slots) ops.push({ op: "layout", slots });
+        break;
+      }
+      case "chart": {
+        if (!isNonEmptyString(o.slot, 80)) break;
+        const spec = validateChartSpec(o.spec);
+        if (!spec) break;
+        ops.push({
+          op: "chart",
+          slot: o.slot,
+          spec,
+          title: isNonEmptyString(o.title, 160) ? o.title : undefined,
+          area: normalizeArea(o.area),
+          span: normalizeSpan(o.span),
+        });
+        break;
+      }
+      case "stat": {
+        if (!isNonEmptyString(o.slot, 80) || !isNonEmptyString(o.label, 120) || !isNonEmptyString(o.value, 80)) break;
+        ops.push({
+          op: "stat",
+          slot: o.slot,
+          label: o.label,
+          value: o.value,
+          trend: o.trend === "up" || o.trend === "down" || o.trend === "flat" ? o.trend : undefined,
+          area: normalizeArea(o.area),
+          span: normalizeSpan(o.span),
+        });
+        break;
+      }
+      case "snippet": {
+        if (!isNonEmptyString(o.slot, 80) || !isNonEmptyString(o.title, 160) || typeof o.code !== "string" || !o.code.trim()) break;
+        ops.push({
+          op: "snippet",
+          slot: o.slot,
+          title: o.title,
+          code: o.code.slice(0, MAGIC_UI_MAX_SNIPPET_CHARS),
+          language: isNonEmptyString(o.language, 40) ? o.language : undefined,
+          area: normalizeArea(o.area),
+          span: normalizeSpan(o.span),
+        });
+        break;
+      }
+      case "open_item": {
+        if (!isNonEmptyString(o.id, 80) || !isNonEmptyString(o.text, 500)) break;
+        ops.push({
+          op: "open_item",
+          id: o.id,
+          text: o.text,
+          kind: typeof o.kind === "string" && OPEN_ITEM_KINDS.has(o.kind) ? (o.kind as "action" | "question" | "blocker") : "action",
+        });
+        break;
+      }
+      case "resolve_item": {
+        if (isNonEmptyString(o.id, 80)) ops.push({ op: "resolve_item", id: o.id });
+        break;
+      }
+      case "decision_log": {
+        if (!isNonEmptyString(o.title, 160) || !isNonEmptyString(o.detail, 500)) break;
+        ops.push({ op: "decision_log", title: o.title, detail: o.detail });
+        break;
+      }
+      case "session_summary": {
+        if (typeof o.text === "string") {
+          ops.push({ op: "session_summary", text: o.text.slice(0, 2_000) });
+        }
+        break;
+      }
+      default:
+        break;
+    }
+  }
+  return ops;
+}
+
+let decisionCounter = 0;
+
+/** Server-generated decision entry (user choices, AI auto-resolutions). */
+export function makeDecisionEntry(
+  source: MagicUiDecisionEntry["source"],
+  title: string,
+  detail: string,
+  now: number,
+  behavior?: "allow" | "deny",
+): MagicUiDecisionEntry {
+  return {
+    id: `dec-${now}-${decisionCounter++}`,
+    ts: now,
+    source,
+    title: title.slice(0, 160),
+    detail: detail.slice(0, 500),
+    behavior,
+  };
+}
+
+function upsertLayout(layout: MagicUiLayoutEntry[], slot: string, area?: MagicUiArea, span?: 1 | 2 | 3): MagicUiLayoutEntry[] {
+  if (!area && !span) return layout;
+  const existing = layout.find((l) => l.slot === slot);
+  const next = layout.filter((l) => l.slot !== slot);
+  next.push({
+    slot,
+    area: area ?? existing?.area ?? "main",
+    span: span ?? existing?.span,
+  });
+  return next;
+}
+
+/**
+ * Fold validated ops into a new state (input state is not mutated).
+ * Enforces the slot budget by evicting the oldest-updated slots first.
+ */
+export function applyOps(
+  state: MagicUiDashboardState,
+  ops: MagicUiOp[],
+  now: number,
+): MagicUiDashboardState {
+  const next: MagicUiDashboardState = {
+    ...state,
+    slots: { ...state.slots },
+    layout: [...state.layout],
+    decisionLog: [...state.decisionLog],
+    openItems: [...state.openItems],
+  };
+
+  for (const op of ops) {
+    switch (op.op) {
+      case "set_slot":
+        next.slots[op.slot] = { title: op.title, html: op.html, updatedAt: now };
+        next.layout = upsertLayout(next.layout, op.slot, op.area, op.span);
+        break;
+      case "remove_slot":
+        delete next.slots[op.slot];
+        next.layout = next.layout.filter((l) => l.slot !== op.slot);
+        break;
+      case "layout":
+        next.layout = op.slots.filter((l) => next.slots[l.slot] !== undefined || ops.some((other) => "slot" in other && other.slot === l.slot));
+        break;
+      case "chart":
+        next.slots[op.slot] = { title: op.title ?? op.spec.title, chart: op.spec, updatedAt: now };
+        next.layout = upsertLayout(next.layout, op.slot, op.area, op.span);
+        break;
+      case "stat":
+        next.slots[op.slot] = { stat: { label: op.label, value: op.value, trend: op.trend }, updatedAt: now };
+        next.layout = upsertLayout(next.layout, op.slot, op.area, op.span);
+        break;
+      case "snippet":
+        next.slots[op.slot] = {
+          title: op.title,
+          snippet: { title: op.title, code: op.code, language: op.language },
+          updatedAt: now,
+        };
+        next.layout = upsertLayout(next.layout, op.slot, op.area, op.span);
+        break;
+      case "open_item": {
+        next.openItems = next.openItems.filter((i) => i.id !== op.id);
+        next.openItems.unshift({ id: op.id, ts: now, text: op.text, kind: op.kind ?? "action" });
+        if (next.openItems.length > MAGIC_UI_MAX_OPEN_ITEMS) {
+          next.openItems = next.openItems.slice(0, MAGIC_UI_MAX_OPEN_ITEMS);
+        }
+        break;
+      }
+      case "resolve_item":
+        next.openItems = next.openItems.filter((i) => i.id !== op.id);
+        break;
+      case "decision_log":
+        next.decisionLog.unshift(makeDecisionEntry("agent", op.title, op.detail, now));
+        if (next.decisionLog.length > MAGIC_UI_MAX_DECISIONS) {
+          next.decisionLog = next.decisionLog.slice(0, MAGIC_UI_MAX_DECISIONS);
+        }
+        break;
+      case "session_summary":
+        next.sessionSummary = op.text;
+        break;
+    }
+  }
+
+  // Slot budget: evict oldest-updated slots beyond the cap.
+  const slotNames = Object.keys(next.slots);
+  if (slotNames.length > MAGIC_UI_MAX_SLOTS) {
+    const byAge = slotNames.sort((a, b) => next.slots[a].updatedAt - next.slots[b].updatedAt);
+    for (const name of byAge.slice(0, slotNames.length - MAGIC_UI_MAX_SLOTS)) {
+      delete next.slots[name];
+      next.layout = next.layout.filter((l) => l.slot !== name);
+    }
+  }
+
+  next.version = state.version + 1;
+  next.updatedAt = now;
+  return next;
+}
+
+/** Append a server-generated decision entry (bumps version so browsers update). */
+export function appendDecision(
+  state: MagicUiDashboardState,
+  entry: MagicUiDecisionEntry,
+): MagicUiDashboardState {
+  const decisionLog = [entry, ...state.decisionLog].slice(0, MAGIC_UI_MAX_DECISIONS);
+  return { ...state, decisionLog, version: state.version + 1, updatedAt: entry.ts };
+}

package/server/magic-ui-settings.test.ts

@@ -0,0 +1,56 @@
+// Tests for the MagicUI effective-settings resolver.
+//
+// Semantics under test (deliberately different from AI validation's
+// inherit-default): the global toggle only makes the feature AVAILABLE;
+// a watcher runs only for sessions that explicitly opted in — a global
+// default-on would silently start a Haiku watcher for every session.
+// CLI availability is a hard gate (subscription login, no API key path).
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import type { SessionState } from "./session-types.js";
+
+const mocks = vi.hoisted(() => ({
+  magicUiEnabled: false,
+  cliAvailable: true,
+}));
+
+vi.mock("./settings-manager.js", () => ({
+  getSettings: () => ({ magicUiEnabled: mocks.magicUiEnabled, magicUiModel: "claude-haiku-4-5" }),
+}));
+vi.mock("./claude-cli-runner.js", () => ({
+  isClaudeCliAvailable: () => mocks.cliAvailable,
+}));
+
+import { getEffectiveMagicUi } from "./magic-ui-settings.js";
+
+function session(magicUiActive: boolean | null | undefined): SessionState {
+  return { session_id: "s", magicUiActive } as SessionState;
+}
+
+beforeEach(() => {
+  mocks.magicUiEnabled = true;
+  mocks.cliAvailable = true;
+});
+
+describe("getEffectiveMagicUi", () => {
+  it("is enabled only with global availability AND explicit session opt-in", () => {
+    expect(getEffectiveMagicUi(session(true)).enabled).toBe(true);
+    expect(getEffectiveMagicUi(session(false)).enabled).toBe(false);
+    // null/undefined = no opt-in → off (never default-on per session)
+    expect(getEffectiveMagicUi(session(null)).enabled).toBe(false);
+    expect(getEffectiveMagicUi(session(undefined)).enabled).toBe(false);
+  });
+
+  it("is disabled when the feature is globally off, even with session opt-in", () => {
+    mocks.magicUiEnabled = false;
+    expect(getEffectiveMagicUi(session(true)).enabled).toBe(false);
+  });
+
+  it("is disabled when the Claude CLI is unavailable (subscription-login gate)", () => {
+    mocks.cliAvailable = false;
+    expect(getEffectiveMagicUi(session(true)).enabled).toBe(false);
+  });
+
+  it("reports the configured watcher model", () => {
+    expect(getEffectiveMagicUi(session(true)).model).toBe("claude-haiku-4-5");
+  });
+});