feat(clique): CLS loop router + live Runway switcher fully wired

- CLSTile Layer C: live Runway video element with 200ms crossfade over
the always-running CLS loop; gold pulse ring while LIVE is active
- useCLSRunner: goLive() checks pre-warm cache (instant) then polls
Runway at 1500ms intervals; returnToLoop() clears live state
- AgentTile: imports useCLSRunner per agent; triggers goLive(speak)
on state==live, returnToLoop on exit; pre-warms speak clip 2s
after mount so next switch is instant; passes liveVideoUrl+onLiveEnded
down to CLSTile
- /api/clique/cls-live: Runway gen4_turbo image_to_video endpoint
with speak/nod/react/explain mood prompts
- Roster: TJ, Dev, Zara, Simone, Finn added (21 members total)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

app/api/clique/cls-live/route.ts

@@ -0,0 +1,105 @@
+import { NextRequest, NextResponse } from "next/server";
+import { CLIQUE_ROSTER } from "@/lib/clique-roster";
+
+/**
+ * CLS Live Clip Generator
+ *
+ * Generates a short Runway video of an agent "going live" — speaking and
+ * gesturing naturally. Used to switch from the CLS idle loop to an authentic
+ * live character moment.
+ *
+ * POST /api/clique/cls-live
+ * Body: { agentId: string, mood?: "speak" | "nod" | "react" | "explain" }
+ * Returns: { taskId, status: "PENDING" }
+ *
+ * GET /api/clique/cls-live?taskId=xxx
+ * Returns: { taskId, status, videoUrl? }
+ */
+
+const RUNWAY_HOST    = "https://api.dev.runwayml.com";
+const RUNWAY_VERSION = "2024-11-06";
+
+const LIVE_PROMPTS: Record<string, string> = {
+  speak:   "person speaking naturally and confidently, slight hand gesture, engaged expression, mouth moving naturally, waist-up portrait, navy blazer, crest on pocket",
+  nod:     "person nodding slowly while listening, thoughtful expression, slight forward lean, waist-up portrait, navy blazer, crest on pocket",
+  react:   "person reacting with warm expression, subtle smile forming, eyes bright and engaged, waist-up portrait, navy blazer, crest on pocket",
+  explain: "person explaining something with a small deliberate hand gesture, clear direct gaze, professional, waist-up portrait, navy blazer, crest on pocket",
+};
+
+const SUFFIX = " Photorealistic. Seamless loopable clip. Cinematic lighting. No cuts.";
+
+async function getPortraitBase64(portraitPath: string): Promise<string> {
+  // portraitPath is like /characters/AMANDA_SHIELD.png — resolve from public/
+  const fs = await import("fs");
+  const path = await import("path");
+  const filePath = path.join(process.cwd(), "public", portraitPath);
+  const buf = fs.readFileSync(filePath);
+  const ext = path.extname(filePath).slice(1).toLowerCase();
+  const mime = ext === "jpg" || ext === "jpeg" ? "image/jpeg" : "image/png";
+  return `data:${mime};base64,${buf.toString("base64")}`;
+}
+
+export async function POST(req: NextRequest) {
+  try {
+    const { agentId, mood = "speak" } = await req.json();
+    if (!agentId) return NextResponse.json({ error: "agentId required" }, { status: 400 });
+
+    const agent = CLIQUE_ROSTER.find(a => a.id === agentId);
+    if (!agent) return NextResponse.json({ error: "Agent not found" }, { status: 404 });
+
+    const promptBase = LIVE_PROMPTS[mood] ?? LIVE_PROMPTS.speak;
+    const promptText = promptBase + SUFFIX;
+
+    const portraitB64 = await getPortraitBase64(agent.portrait);
+
+    const body = {
+      model: "gen4_turbo",
+      promptImage: portraitB64,
+      promptText,
+      duration: 5,
+      ratio: "720:1280",
+    };
+
+    const res = await fetch(`${RUNWAY_HOST}/v1/image_to_video`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${process.env.RUNWAY_API_KEY}`,
+        "X-Runway-Version": RUNWAY_VERSION,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(body),
+    });
+
+    if (!res.ok) {
+      return NextResponse.json({ error: await res.text() }, { status: res.status });
+    }
+
+    const data = await res.json();
+    return NextResponse.json({ taskId: data.id, status: "PENDING", agentId, mood });
+  } catch (e) {
+    return NextResponse.json({ error: String(e) }, { status: 500 });
+  }
+}
+
+export async function GET(req: NextRequest) {
+  const taskId = req.nextUrl.searchParams.get("taskId");
+  if (!taskId) return NextResponse.json({ error: "taskId required" }, { status: 400 });
+
+  const res = await fetch(`${RUNWAY_HOST}/v1/tasks/${taskId}`, {
+    headers: {
+      Authorization: `Bearer ${process.env.RUNWAY_API_KEY}`,
+      "X-Runway-Version": RUNWAY_VERSION,
+    },
+  });
+
+  if (!res.ok) return NextResponse.json({ error: await res.text() }, { status: res.status });
+
+  const data = await res.json();
+  if (data.status === "SUCCEEDED") {
+    return NextResponse.json({ taskId, status: "SUCCEEDED", videoUrl: data.output?.[0] ?? null });
+  }
+  if (data.status === "FAILED") {
+    return NextResponse.json({ taskId, status: "FAILED", error: data.failure }, { status: 500 });
+  }
+  return NextResponse.json({ taskId, status: data.status, videoUrl: null });
+}

components/clique/AgentTile.tsx

@@ -1,10 +1,11 @@
 "use client";
-import { useMemo } from "react";
+import { useEffect, useMemo } from "react";
 import { CliqueAgent } from "@/lib/clique-roster";
 import { QCRProfile, rapportColor, rapportLabel } from "@/lib/qcr";
 import CLSTile from "./CLSTile";
 import { CLSVariant } from "@/lib/clique-cls";
 import { CLSRouterState } from "@/lib/cls-loop-router";
+import { useCLSRunner } from "@/lib/use-cls-runner";
 
 interface Props {
   agent: CliqueAgent;
@@ -39,6 +40,28 @@ export default function AgentTile({ agent, state, size = "md", qcr, onClick, cls
   const moodColor = MOOD_COLOR[qcr?.moodRead ?? "neutral"];
   const showDesire = desire > 0.75 && !isLive;
 
+  // CLS ↔ Live Runway switcher for this specific agent
+  const { liveVideoUrl, goLive, returnToLoop, prewarm } = useCLSRunner(agent.id);
+
+  // Trigger goLive when parent sets state to "live", clean up when leaving
+  useEffect(() => {
+    if (isLive) {
+      goLive("speak");
+    } else {
+      returnToLoop();
+    }
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [isLive]);
+
+  // Pre-warm "speak" clip as soon as agent enters listening state
+  useEffect(() => {
+    if (!isLive && !isOff) {
+      const t = setTimeout(() => prewarm("speak"), 2_000);
+      return () => clearTimeout(t);
+    }
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [isLive, isOff]);
+
   // Stable variant override per mount — only used when router is bypassed
   const variantOverride = useMemo(
     () => clsVariant ?? undefined,
@@ -101,7 +124,7 @@ export default function AgentTile({ agent, state, size = "md", qcr, onClick, cls
         flexShrink: 0,
         animation: isLive ? `live-ring-${agent.id} 1.2s ease-out infinite` : "none",
       }}>
-        {/* CLS animated loop — always alive, never a frozen image */}
+        {/* CLS animated loop + live Runway layer */}
         <CLSTile
           agent={agent}
           clsState={routerState}
@@ -109,6 +132,8 @@ export default function AgentTile({ agent, state, size = "md", qcr, onClick, cls
           size={dim}
           borderRadius={borderRadius}
           isCSA={agent.isCSA}
+          liveVideoUrl={liveVideoUrl}
+          onLiveEnded={returnToLoop}
         />
 
         {/* LIVE gradient overlay */}

components/clique/CLSTile.tsx

@@ -27,11 +27,19 @@ interface Props {
   isCSA?: boolean;
   onReady?: () => void;
   onStateComplete?: (state: CLSRouterState) => void;
+  /**
+   * Live Runway video URL — when set, instantly crossfades from CLS loop
+   * to the live clip. Clear to null to return to CLS loop.
+   */
+  liveVideoUrl?: string | null;
+  /** Called when the live Runway clip finishes playing — parent should returnToLoop() */
+  onLiveEnded?: () => void;
 }
 
 export default function CLSTile({
   agent, clsState = "listen", variant: variantOverride,
   size, borderRadius = 8, isCSA, onReady, onStateComplete,
+  liveVideoUrl, onLiveEnded,
 }: Props) {
   const { currentVariant, nextVariant, transitioning } = useCLSLoopRouter(
     agent.id,
@@ -61,7 +69,9 @@ export default function CLSTile({
     bRef.current?.load();
   }, [bVariant]);
 
-  const FADE = "opacity 0.6s ease-in-out";
+  const FADE      = "opacity 0.6s ease-in-out";
+  const LIVE_FADE = "opacity 0.2s ease-in-out"; // live switch is faster — near-instant
+  const showLive  = !!liveVideoUrl;
 
   return (
     <div style={{
@@ -168,6 +178,48 @@ export default function CLSTile({
           )}
         </>
       )}
+
+      {/* ── LAYER C: LIVE RUNWAY VIDEO ─────────────────────────────────────
+          Sits on top of everything. Fades in instantly when liveVideoUrl is
+          set, fades out when cleared. The CLS loop keeps playing underneath
+          so the return transition is seamless.
+      ──────────────────────────────────────────────────────────────────── */}
+      {liveVideoUrl && (
+        <video
+          key={liveVideoUrl}
+          src={liveVideoUrl}
+          autoPlay
+          muted
+          playsInline
+          onEnded={onLiveEnded}
+          style={{
+            position: "absolute", inset: 0,
+            width: "100%", height: "100%",
+            objectFit: "cover", objectPosition: "top center",
+            opacity: showLive ? 1 : 0,
+            transition: LIVE_FADE,
+            zIndex: 10,
+          }}
+        />
+      )}
+
+      {/* Gold LIVE pulse ring — shows while Runway layer is active */}
+      {showLive && (
+        <div style={{
+          position: "absolute", inset: 0,
+          borderRadius,
+          boxShadow: "inset 0 0 0 2px rgba(200,169,81,0.6), 0 0 20px rgba(200,169,81,0.3)",
+          zIndex: 11,
+          pointerEvents: "none",
+          animation: "live-pulse 1.5s ease-in-out infinite",
+        }} />
+      )}
+      <style>{`
+        @keyframes live-pulse {
+          0%,100% { box-shadow: inset 0 0 0 2px rgba(200,169,81,0.4), 0 0 14px rgba(200,169,81,0.2); }
+          50%      { box-shadow: inset 0 0 0 3px rgba(200,169,81,0.9), 0 0 28px rgba(200,169,81,0.5); }
+        }
+      `}</style>
     </div>
   );
 }

lib/clique-roster.ts

@@ -32,9 +32,9 @@ export const CLIQUE_ROSTER: CliqueAgent[] = [
   { id:"cleo",    name:"Cleo",    role:"Minutes & Meetings",          voice:"sage",    gstackRole:"retro",            persona:"Historian of the clique. Captures every decision, action item, and insight with surgical precision. Nothing is missed. Nothing is padded.", portrait:"/characters/CLEO_SHIELD.png",    color:"#c8a951", status:"available" },
   { id:"zara",   name:"Zara",   role:"Brand Strategy",              voice:"coral",   gstackRole:"landing-report",   persona:"Brand architect. Controls the narrative — voice, presence, and cultural resonance. Nothing ships without her eye on it.",                  portrait:"/characters/ZARA_SHIELD.png",   color:"#c8a951", status:"available" },
   { id:"simone", name:"Simone", role:"UX Research",                 voice:"sage",    gstackRole:"grill-with-docs",  persona:"User advocate. Translates real behavior into design truth. Challenges assumptions with receipts.",                                       portrait:"/characters/SIMONE_SHIELD.png", color:"#4CAF50", status:"available" },
-  { id:"cole",   name:"Cole",   role:"Cloud Architecture",          voice:"onyx",    gstackRole:"plan-eng-review",  persona:"Infrastructure obsessive. Builds systems that scale before they need to. Quiet until it matters.",                                       portrait:"/characters/COLE_SHIELD.png",   color:"#1a5f7a", status:"available" },
+  { id:"tj",     name:"TJ",     role:"Founder",                     voice:"onyx",    gstackRole:"plan-eng-review",  persona:"The architect of the whole operation. Vision, conviction, and the last word.",                                                             portrait:"/characters/TJ_SHIELD.png",     color:"#c8a951", status:"available" },
   { id:"finn",   name:"Finn",   role:"Machine Learning",            voice:"ash",     gstackRole:"autoplan",         persona:"Model whisperer. Finds the training shortcut nobody else saw. Moves fast and ships working prototypes.",                                  portrait:"/characters/FINN_SHIELD.png",   color:"#4CAF50", status:"available" },
-  { id:"rhys",   name:"Rhys",   role:"Security",                    voice:"echo",    gstackRole:"review",           persona:"Threat modeler. Finds the hole before the adversary does. The one person in the room nobody argues with.",                               portrait:"/characters/RHYS_SHIELD.png",   color:"#dc3c3c", status:"available" },
+  { id:"dev",    name:"Dev",    role:"Security",                    voice:"echo",    gstackRole:"review",           persona:"Threat modeler. Finds the hole before the adversary does. The one person in the room nobody argues with.",                               portrait:"/characters/DEV_SHIELD.png",    color:"#dc3c3c", status:"available" },
 ];
 
 // Default 9-member team → >6 → grid layout, user featured top

lib/use-cls-runner.ts

@@ -0,0 +1,143 @@
+"use client";
+/**
+ * useCLSRunner — CLS ↔ Live Runway Switcher
+ *
+ * Orchestrates the full lifecycle for one agent:
+ *   CLS loop (idle)  →  generate Runway clip  →  instant switch to LIVE  →  return to CLS
+ *
+ * The switch from loop → live happens in < 200ms once the Runway clip is ready.
+ * Clips are pre-generated speculatively so the switch feels instant to the user.
+ *
+ * Usage:
+ *   const { liveVideoUrl, isLive, goLive, returnToLoop } = useCLSRunner(agentId);
+ *   // Pass liveVideoUrl to CLSTile — it handles the visual crossfade.
+ */
+
+import { useCallback, useEffect, useRef, useState } from "react";
+
+export type LiveMood = "speak" | "nod" | "react" | "explain";
+
+export interface CLSRunnerHandle {
+  /** URL of the ready Runway live clip — null while in CLS loop mode */
+  liveVideoUrl: string | null;
+  /** True when the live Runway layer is showing */
+  isLive: boolean;
+  /** True while a Runway clip is being generated */
+  isGenerating: boolean;
+  /** Trigger a live moment — generates clip + switches instantly when ready */
+  goLive: (mood?: LiveMood) => void;
+  /** Return to CLS idle loop */
+  returnToLoop: () => void;
+  /** Pre-warm: silently generate a clip in background so next goLive() is instant */
+  prewarm: (mood?: LiveMood) => void;
+}
+
+const POLL_INTERVAL_MS = 1_500;
+
+export function useCLSRunner(agentId: string): CLSRunnerHandle {
+  const [liveVideoUrl, setLiveVideoUrl] = useState<string | null>(null);
+  const [isLive,       setIsLive]       = useState(false);
+  const [isGenerating, setIsGenerating] = useState(false);
+
+  // Pre-warmed clip cache: mood → url
+  const cache      = useRef<Map<string, string>>(new Map());
+  const pollTimer  = useRef<ReturnType<typeof setInterval> | null>(null);
+  const currentTask= useRef<string | null>(null);
+  const pendingMood= useRef<LiveMood>("speak");
+  const unmounted  = useRef(false);
+
+  useEffect(() => () => { unmounted.current = true; stopPoll(); }, []);
+
+  function stopPoll() {
+    if (pollTimer.current) { clearInterval(pollTimer.current); pollTimer.current = null; }
+  }
+
+  async function submitTask(mood: LiveMood): Promise<string | null> {
+    try {
+      const res = await fetch("/api/clique/cls-live", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ agentId, mood }),
+      });
+      if (!res.ok) return null;
+      const { taskId } = await res.json();
+      return taskId ?? null;
+    } catch { return null; }
+  }
+
+  async function pollTask(taskId: string): Promise<string | null> {
+    try {
+      const res = await fetch(`/api/clique/cls-live?taskId=${taskId}`);
+      if (!res.ok) return null;
+      const data = await res.json();
+      if (data.status === "SUCCEEDED") return data.videoUrl ?? null;
+      if (data.status === "FAILED")    return null;
+      return undefined as unknown as null; // still running
+    } catch { return null; }
+  }
+
+  // ── goLive ────────────────────────────────────────────────────────────────
+  const goLive = useCallback(async (mood: LiveMood = "speak") => {
+    if (unmounted.current) return;
+    pendingMood.current = mood;
+
+    // 1. Check cache first — instant switch
+    const cached = cache.current.get(mood);
+    if (cached) {
+      setLiveVideoUrl(cached);
+      setIsLive(true);
+      cache.current.delete(mood); // consume it
+      return;
+    }
+
+    // 2. Not cached — generate now and switch when ready
+    setIsGenerating(true);
+    const taskId = await submitTask(mood);
+    if (!taskId || unmounted.current) { setIsGenerating(false); return; }
+    currentTask.current = taskId;
+
+    stopPoll();
+    pollTimer.current = setInterval(async () => {
+      if (unmounted.current) { stopPoll(); return; }
+      const url = await pollTask(currentTask.current!);
+      if (url === null) { stopPoll(); setIsGenerating(false); return; } // failed
+      if (typeof url === "string" && url.length > 0) {
+        stopPoll();
+        setIsGenerating(false);
+        if (unmounted.current) return;
+        setLiveVideoUrl(url);
+        setIsLive(true);
+      }
+      // undefined = still running, keep polling
+    }, POLL_INTERVAL_MS);
+  }, [agentId]);
+
+  // ── returnToLoop ──────────────────────────────────────────────────────────
+  const returnToLoop = useCallback(() => {
+    stopPoll();
+    setIsLive(false);
+    setLiveVideoUrl(null);
+    setIsGenerating(false);
+    currentTask.current = null;
+  }, []);
+
+  // ── prewarm ───────────────────────────────────────────────────────────────
+  const prewarm = useCallback(async (mood: LiveMood = "speak") => {
+    if (cache.current.has(mood) || unmounted.current) return;
+
+    const taskId = await submitTask(mood);
+    if (!taskId) return;
+
+    const timer = setInterval(async () => {
+      if (unmounted.current) { clearInterval(timer); return; }
+      const url = await pollTask(taskId);
+      if (typeof url === "string" && url.length > 0) {
+        clearInterval(timer);
+        cache.current.set(mood, url);
+      }
+      if (url === null) clearInterval(timer); // failed silently
+    }, POLL_INTERVAL_MS);
+  }, [agentId]);
+
+  return { liveVideoUrl, isLive, isGenerating, goLive, returnToLoop, prewarm };
+}