@a-t-h-i/bot-lobby 0.2.0 → 0.3.0

package/README.md

@@ -118,8 +118,16 @@ and the built-in spinner are hidden, and a widget above the editor animates the
 task. At 72 columns and wider it draws a large scene: a header box with the task
 title and state in its top border, a progress bar, and a metadata row with
 elapsed time, quiet-mode hint and task id; an oracle tower with a twinkling
-aura (drifting z's while dormant), a radiant orb crown, window eyes, a
-seven-column mouth and its ORC door; beside the crown, the oracle's speech
+aura (drifting z's while dormant), a radiant orb crown, two window eyes, a
+seven-column mouth and its ORC door. Its pupils look around: they move
+left, centre or right in each window and turn up `◓`, ahead `◉` or down `◒`.
+While agents work it looks down at them, taking turns between them; while it
+talks it looks at you; otherwise its eyes wander the room and keep returning
+to you. It keeps a straight, serious face (`───`), tightening into a frown
+only when the task is blocked, and its mouth lip-syncs as a voice waveform
+for ~2 s whenever it says something new. Every 6–12 s it blinks (lids
+stepping down and up) or scans the whole room; asleep, it peeks one eye open
+or snores. Beside the crown, the oracle's speech
 bubble, its tail on the orb, says what the master is doing (`⠋ delegating`,
 `⠋ thinking`, `· your turn` once its turn ends, `· dormant` when paused) above
 who is at work (`→ DEV · QA`), the current step (`step 3 of 7`) or the task
@@ -134,9 +142,9 @@ terminals keep the
 boxed banner, header and compact animated strip, whose working line names the
 newest running agent's activity and elapsed time. Each sprite rests on one calm
 face and, independently every 20–30 s, briefly blinks (~500 ms) or emotes
-(~2 s, stepping through its kaomoji frames); the oracle's mouth moves with its
+(~2 s, stepping through its kaomoji frames), all on one
 adaptive clock — 250 ms while work is live, 1 s when idle and ~120 ms while an
-expression plays — and their faces, colours and words follow each agent's status
+expression plays or the oracle talks — and their faces, colours and words follow each agent's status
 (working, idle, done, failed). The large scene's rest and blink frames stay the
 five-column ASCII eyes, while its emote frames are status-aware kaomoji: nervous
 while working, happy when done (QA flexes and dances), scared on failure. The

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a-t-h-i/bot-lobby",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Structured multi-agent software engineering orchestrator for Pi",
   "type": "module",
   "license": "Apache-2.0",

package/src/pi/expressions.ts

@@ -44,9 +44,20 @@ function unit(rng: () => number): number {
   return Number.isFinite(value) ? Math.min(1, Math.max(0, value)) : 0;
 }
 
-/** Random resting gap before the next expression, in `[BLINK_MIN_MS, BLINK_MAX_MS]`. */
-export function nextGap(rng: () => number): number {
-  return BLINK_MIN_MS + Math.round(unit(rng) * (BLINK_MAX_MS - BLINK_MIN_MS));
+/** Resting window between expressions, milliseconds. */
+export interface ExpressionGap {
+  min: number;
+  max: number;
+}
+
+/** Agent slots rest 20-30 s between expressions. */
+export const SLOT_GAP: ExpressionGap = { min: BLINK_MIN_MS, max: BLINK_MAX_MS };
+/** The oracle is the scene's centrepiece: it blinks and emotes every 6-12 s. */
+export const ORACLE_GAP: ExpressionGap = { min: 6_000, max: 12_000 };
+
+/** Random resting gap before the next expression, inside `gap` (the slot window by default). */
+export function nextGap(rng: () => number, gap: ExpressionGap = SLOT_GAP): number {
+  return gap.min + Math.round(unit(rng) * (gap.max - gap.min));
 }
 
 /** Whether the next expression blinks (~65%) or emotes (~35%). */
@@ -55,9 +66,9 @@ export function pickEvent(rng: () => number): "blink" | "emote" {
 }
 
 /** A freshly rested expression that fires for the first time after one random gap. */
-export function createExpression(now: number, rng: () => number): ExpressionState {
+export function createExpression(now: number, rng: () => number, gap: ExpressionGap = SLOT_GAP): ExpressionState {
   const start = Number.isFinite(now) ? now : 0;
-  return { nextAt: start + nextGap(rng), until: start, startedAt: start, frame: REST_FRAME };
+  return { nextAt: start + nextGap(rng, gap), until: start, startedAt: start, frame: REST_FRAME };
 }
 
 /** True while `now` is inside a playing blink or emote. */
@@ -74,17 +85,43 @@ export function anyPlaying(states: readonly ExpressionState[], now: number): boo
  * Advance one sprite to `now`: start a blink or emote once the gap has elapsed,
  * drop back to the rest frame when it ends, and change nothing in between.
  */
-export function advanceExpression(state: ExpressionState, now: number, rng: () => number): ExpressionState {
+export function advanceExpression(
+  state: ExpressionState,
+  now: number,
+  rng: () => number,
+  gap: ExpressionGap = SLOT_GAP,
+): ExpressionState {
   if (!Number.isFinite(now)) return state;
   if (now < state.until) return state.frame >= EMOTE_FRAME ? steppedEmote(state, now) : state;
   if (now < state.nextAt) return state.frame === REST_FRAME ? state : { ...state, frame: REST_FRAME };
-  return play(now, rng);
+  return play(now, rng, gap);
 }
 
-function play(now: number, rng: () => number): ExpressionState {
+function play(now: number, rng: () => number, gap: ExpressionGap): ExpressionState {
   const blink = pickEvent(rng) === "blink";
   const until = now + (blink ? BLINK_MS : EMOTE_MS);
-  return { nextAt: until + nextGap(rng), until, startedAt: now, frame: blink ? BLINK_FRAME : EMOTE_FRAME };
+  return { nextAt: until + nextGap(rng, gap), until, startedAt: now, frame: blink ? BLINK_FRAME : EMOTE_FRAME };
+}
+
+/** One sub-step of a playing expression; the oracle's blink and glance step through these. */
+export const PHASE_MS = FAST_TICK_MS;
+
+/** Sub-steps elapsed in the playing expression, 0 while resting or on a bad clock. */
+export function expressionPhase(state: ExpressionState, now: number): number {
+  if (!isPlaying(state, now)) return 0;
+  const elapsed = now - state.startedAt;
+  return Number.isFinite(elapsed) && elapsed > 0 ? Math.floor(elapsed / PHASE_MS) : 0;
+}
+
+/** How long the oracle lip-syncs after it says something new, and one mouth shape's hold. */
+export const TALK_MS = 1800;
+export const TALK_STEP_MS = FAST_TICK_MS;
+
+/** Mouth-shape index while the oracle is still talking about what it said at `since`, else undefined. */
+export function talkFrame(since: number | undefined, now: number): number | undefined {
+  if (since === undefined || !Number.isFinite(since) || !Number.isFinite(now)) return undefined;
+  const elapsed = now - since;
+  return elapsed >= 0 && elapsed < TALK_MS ? Math.floor(elapsed / TALK_STEP_MS) : undefined;
 }
 
 /** Emote frame for `now`: one step per EMOTE_STEP_MS, clamped to the last frame. */

package/src/pi/mascot-art.ts

@@ -6,7 +6,7 @@ import type { TaskState } from "../schemas/task.ts";
  * that `zen.ts` and `zen-large.ts` compose. Every glyph is exactly one visible
  * column so the art stays narrow/ambiguous-width safe: the non-ASCII glyphs are
  * the lobby `⌂` in `BANNER_NARROW`, the panel's ◐/✓/✗ status family, and the
- * box-drawing, bar, eye and aura glyphs of the large scene (─ │ ┌ ┐ └ ┘ ╭ ╮ ╰ ╯ ╲ ╱ ╶ ├ ┤ ┬ ┴ █ ▓ ▒ ░ ▁ ▂ ▃ ◉ ◍ ◎ ◌ ○ ✦ ✧).
+ * box-drawing, bar, eye and aura glyphs of the large scene (─ │ ┌ ┐ └ ┘ ╭ ╮ ╰ ╯ ╲ ╱ ╶ ├ ┤ ┬ ┴ █ ▓ ▒ ░ ▁-▇ ◉ ◍ ◎ ◌ ○ ◓ ◒ ✦ ✧).
  */
 
 /**
@@ -105,36 +105,135 @@ export const ORACLE_COLORS: Record<OraclePose, { color: PanelColor; bold: boolea
   dormant: { color: "dim", bold: false },
 };
 
-/** One oracle frame: the crown orb, both window eyes and the seven-column mouth. */
+/** One oracle frame: the crown orb, both pupils and the seven-column mouth. */
 export interface OracleFrame {
   orb: string;
+  /**
+   * One-column pupil drawn inside its three-column eye window: `OPEN_EYE` takes
+   * the gaze's pupil, `CLOSED_EYE` fills the window as a lid, anything else is drawn as is.
+   */
   winL: string;
   winR: string;
   /** Exactly seven one-column glyphs; never moves the tower geometry. */
   mouth: string;
 }
 
+/** Oracle expression frame indexes, matching the shared schedule (see expressions.ts). */
+export const ORACLE_REST = 0;
+export const ORACLE_BLINK = 1;
+/** Both emote frames are the look-around; the second only dims the orb. */
+export const ORACLE_LOOK = 2;
+
+/** An open eye: its pupil comes from where the oracle is looking. */
+export const OPEN_EYE = "◉";
+/** A closed eye: the lid fills the whole window. */
+export const CLOSED_EYE = "─";
+/** A half-closed lid, mid-blink or half-asleep. */
+export const HALF_LID = "◒";
+/** Inner width of each eye window; the pupil moves across it. */
+export const EYE_WIDTH = 3;
+
+/** The oracle's straight, serious mouth: it never idles on a smile. */
+export const ORACLE_MOUTH = "  ───  ";
+
 /**
- * Indexed oracle expressions per pose: 0 rests, 1 blinks and 2-3 emote. While
- * orchestrating the oracle glances around (2) and speaks (3); dormant, it sleeps
- * with closed eyes, peeks (1) and snores (2). Every glyph is one column and every
- * mouth seven, so a frame swap never moves the tower geometry.
+ * Indexed oracle expressions per pose: rest, blink, then the two emote steps.
+ * Orchestrating, the oracle keeps a straight face and its emotes are a look
+ * around the room; dormant, it sleeps, peeks one eye open and snores (o, then O).
+ * While it talks the mouth lip-syncs instead.
  */
 export const ORACLE_FRAMES: Record<OraclePose, readonly OracleFrame[]> = {
   orchestrating: [
-    { orb: "◉", winL: "◉", winR: "◉", mouth: " ╰───╯ " },
-    { orb: "◉", winL: "─", winR: "─", mouth: " ╰───╯ " },
-    { orb: "◎", winL: "◍", winR: "◉", mouth: "  ───  " },
-    { orb: "◍", winL: "◉", winR: "◍", mouth: " ▁▂▃▂▁ " },
+    { orb: "◉", winL: OPEN_EYE, winR: OPEN_EYE, mouth: ORACLE_MOUTH },
+    { orb: "◉", winL: CLOSED_EYE, winR: CLOSED_EYE, mouth: ORACLE_MOUTH },
+    { orb: "◎", winL: OPEN_EYE, winR: OPEN_EYE, mouth: ORACLE_MOUTH },
+    { orb: "◍", winL: OPEN_EYE, winR: OPEN_EYE, mouth: ORACLE_MOUTH },
   ],
   dormant: [
-    { orb: "◌", winL: "─", winR: "─", mouth: "  ───  " },
-    { orb: "◌", winL: "◌", winR: "─", mouth: "  ───  " },
-    { orb: "○", winL: "─", winR: "─", mouth: "  ─o─  " },
-    { orb: "○", winL: "─", winR: "─", mouth: "  ───  " },
+    { orb: "◌", winL: CLOSED_EYE, winR: CLOSED_EYE, mouth: ORACLE_MOUTH },
+    { orb: "◌", winL: HALF_LID, winR: CLOSED_EYE, mouth: ORACLE_MOUTH },
+    { orb: "○", winL: CLOSED_EYE, winR: CLOSED_EYE, mouth: "  ─o─  " },
+    { orb: "○", winL: CLOSED_EYE, winR: CLOSED_EYE, mouth: "  ─O─  " },
   ],
 };
 
+/**
+ * Lid positions stepped through by a blink (one per `PHASE_MS`, the last held):
+ * half-lidded, shut, shut, half-lidded. Dormant, the "blink" is a sleepy peek:
+ * the left eye cracks open, looks, and drifts shut again.
+ */
+export const ORACLE_BLINKS: Record<OraclePose, readonly (readonly [string, string])[]> = {
+  orchestrating: [[HALF_LID, HALF_LID], [CLOSED_EYE, CLOSED_EYE], [CLOSED_EYE, CLOSED_EYE], [HALF_LID, HALF_LID]],
+  dormant: [[HALF_LID, CLOSED_EYE], [OPEN_EYE, CLOSED_EYE], [OPEN_EYE, CLOSED_EYE], [OPEN_EYE, CLOSED_EYE], [HALF_LID, CLOSED_EYE], [CLOSED_EYE, CLOSED_EYE]],
+};
+
+/**
+ * Where the pupils look. `x` moves the pupil across its three-column window
+ * (left, centre, right); `y` swaps its glyph, since the window is one row:
+ * `◓` looks up, `◉` straight ahead, `◒` down.
+ */
+export interface Gaze {
+  x: -1 | 0 | 1;
+  y: -1 | 0 | 1;
+}
+
+export const GAZE_AHEAD: Gaze = { x: 0, y: 0 };
+
+/** The pupil glyph for each vertical gaze. */
+export const ORACLE_PUPILS: Record<Gaze["y"], string> = { [-1]: "◓", 0: "◉", 1: "◒" };
+
+const look = (x: Gaze["x"], y: Gaze["y"]): Gaze => ({ x, y });
+
+/**
+ * The look-around emote, one step per `PHASE_MS` across both emote frames
+ * (~2 s): a slow scan left, up across the ceiling, right, down at the agents
+ * and back to you.
+ */
+export const ORACLE_LOOK_PATH: readonly Gaze[] = [
+  look(0, 0), look(-1, 0), look(-1, 0), look(-1, 0), look(-1, -1), look(-1, -1),
+  look(0, -1), look(1, -1), look(1, -1), look(1, 0), look(1, 0), look(1, 0),
+  look(1, 1), look(0, 1), look(0, 1), look(-1, 1), look(0, 0), look(0, 0),
+];
+
+/**
+ * Idle wandering when nothing holds the oracle's attention: it keeps returning
+ * to you between glances around the room. Starts looking ahead.
+ */
+export const ORACLE_WANDER: readonly Gaze[] = [
+  look(0, 0), look(-1, 0), look(0, 0), look(1, -1), look(1, 0), look(0, 0),
+  look(-1, 1), look(0, -1), look(0, 0), look(1, 1), look(-1, -1), look(0, 0),
+];
+
+/** Ticks the eyes hold one wandering spot (~2.5 s while work is live). */
+export const ORACLE_WANDER_TICKS = 10;
+
+/**
+ * Lip-sync while the oracle talks: a voice waveform that swells and falls, with
+ * a closed-mouth breath so it reads as phrases rather than a buzz.
+ */
+export const ORACLE_TALK: readonly string[] = [
+  " ▁▃▅▃▁ ",
+  "  ▂▆▂  ",
+  " ▂▄▇▄▂ ",
+  "  ▁▂▁  ",
+  " ▃▅▂▅▃ ",
+  " ▁▂▄▂▁ ",
+  "   ▁   ",
+  ORACLE_MOUTH,
+];
+
+/** The oracle's resting mood: steady by default, worried when the task is blocked. */
+export type OracleMood = "steady" | "worried";
+
+/** The resting mouth per mood: straight, or a tight frown when blocked. */
+export const ORACLE_MOOD_MOUTHS: Record<OracleMood, string> = {
+  steady: ORACLE_MOUTH,
+  worried: "  ╭─╮  ",
+};
+
+/** Ticks the eyes hold on one working agent before glancing to the next. */
+export const ORACLE_GAZE_TICKS = 8;
+
 /**
  * The seven-column aura above the crown, stepped by the spinner tick: sparkles
  * twinkle while the oracle orchestrates, and z's drift up while it sleeps.
@@ -223,8 +322,9 @@ export const COMPACT_FRAMES: Record<SlotId, Record<SlotState, readonly string[]>
 /**
  * The oracle tower: 13 columns wide, `rows` while height allows and `smallRows`
  * when it must shrink. `{aura}` twinkles over the radiant `{orb}` crown,
- * `{winL}`/`{winR}` are the two window eyes, `{mouth}` speaks and `{door}` is
- * the name over the door. The speech bubble hangs beside the crown.
+ * `{winL}`/`{winR}` are the three-column eye windows the pupils move in,
+ * `{mouth}` speaks and `{door}` is the name over the door. The speech bubble
+ * hangs beside the crown.
  */
 export interface TowerSpec {
   rows: readonly string[];
@@ -244,9 +344,9 @@ export const TOWER: TowerSpec = {
     "    ╱ │ ╲    ",
     "      │      ",
     "╭─────┴─────╮",
-    "│ ╭─╮   ╭─╮ │",
-    "│ │{winL}│   │{winR}│ │",
-    "│ ╰─╯   ╰─╯ │",
+    "│╭───╮ ╭───╮│",
+    "││{winL}│ │{winR}││",
+    "│╰───╯ ╰───╯│",
     "│  {mouth}  │",
     "├───┬───┬───┤",
     "│░▒▓│{door}│▓▒░│",
@@ -255,7 +355,7 @@ export const TOWER: TowerSpec = {
   smallRows: [
     "   ──({orb})──   ",
     "╭─────┴─────╮",
-    "│ │{winL}│   │{winR}│ │",
+    "││{winL}│ │{winR}││",
     "│░▒▓│{door}│▓▒░│",
     "└───┴───┴───┘",
   ],

package/src/pi/ui.ts

@@ -4,10 +4,22 @@ import type { AgentRun } from "../schemas/findings.ts";
 import { TERMINAL_STATES, type Task } from "../schemas/task.ts";
 import { activeTask } from "../state/persistence.ts";
 import { detectProjectRoot } from "../state/project.ts";
-import { advanceExpression, anyPlaying, createExpression, FAST_TICK_MS, type ExpressionState } from "./expressions.ts";
+import {
+  advanceExpression,
+  anyPlaying,
+  createExpression,
+  expressionPhase,
+  FAST_TICK_MS,
+  ORACLE_GAP,
+  SLOT_GAP,
+  talkFrame,
+  type ExpressionGap,
+  type ExpressionState,
+} from "./expressions.ts";
+import { ORACLE_THINKING } from "./activity.ts";
 import { SLOT_IDS } from "./mascot-art.ts";
 import { isQuiet, isSubagentProcess, toggleQuiet } from "./quiet.ts";
-import { panelLines, type ExpressionFrames } from "./zen.ts";
+import { panelLines, type ExpressionFrames, type OracleMotion } from "./zen.ts";
 
 export const STATUS_KEY = "bot-lobby";
 
@@ -48,12 +60,18 @@ function touch(): void {
 }
 
 /** Record the master's current activity word (see events.ts); undefined means it waits on the user. */
-export function setOracleActivity(activity: string | undefined): void {
+export function setOracleActivity(activity: string | undefined, now = Date.now()): void {
   if (activity === oracleActivity) return;
   oracleActivity = activity;
+  // The oracle speaks when it names something new, including handing you the turn;
+  // quietly going back to "thinking" between tool calls is not worth a word.
+  if (activity !== ORACLE_THINKING) oracleSpokeAt = now;
   touch();
 }
 
+/** When the oracle last said something new; its mouth lip-syncs for `TALK_MS` after. */
+let oracleSpokeAt: number | undefined;
+
 /** Upper bound on retained runs so a long task cannot grow the widget state without limit. */
 export const MAX_RETAINED_RUNS = 128;
 
@@ -131,9 +149,9 @@ function liveTickDelay(): number {
   return isLive() ? LIVE_TICK_MS : IDLE_TICK_MS;
 }
 
-/** Tick delay for the zen clock: fastest while an expression plays, so no blink or emote step is skipped. */
-export function expressionTickDelay(states: readonly ExpressionState[], now: number, live: boolean): number {
-  if (anyPlaying(states, now)) return FAST_TICK_MS;
+/** Tick delay for the zen clock: fastest while an expression plays or the oracle talks, so no step is skipped. */
+export function expressionTickDelay(states: readonly ExpressionState[], now: number, live: boolean, talking = false): number {
+  if (talking || anyPlaying(states, now)) return FAST_TICK_MS;
   return live ? LIVE_TICK_MS : IDLE_TICK_MS;
 }
 
@@ -141,6 +159,11 @@ export function expressionTickDelay(states: readonly ExpressionState[], now: num
 type ExpressionKey = keyof ExpressionFrames;
 const EXPRESSION_KEYS: readonly ExpressionKey[] = [...SLOT_IDS, "oracle"];
 
+/** The oracle keeps a livelier schedule than the agent slots. */
+function gapFor(key: ExpressionKey): ExpressionGap {
+  return key === "oracle" ? ORACLE_GAP : SLOT_GAP;
+}
+
 /** Animated zen scene + plan checklist shown above the editor while a task is active. */
 class ZenWidget implements Component {
   private tick = 0;
@@ -158,7 +181,7 @@ class ZenWidget implements Component {
     this.theme = theme;
     this.rng = rng;
     const now = Date.now();
-    const entries = EXPRESSION_KEYS.map((key) => [key, createExpression(now, rng)] as const);
+    const entries = EXPRESSION_KEYS.map((key) => [key, createExpression(now, rng, gapFor(key))] as const);
     this.expressions = Object.fromEntries(entries) as Record<ExpressionKey, ExpressionState>;
     this.timer = setInterval(() => this.advance(), this.delay);
     mountedWidget = this;
@@ -179,18 +202,22 @@ class ZenWidget implements Component {
   }
 
   private play(now: number): void {
-    for (const key of EXPRESSION_KEYS) this.expressions[key] = advanceExpression(this.expressions[key], now, this.rng);
+    for (const key of EXPRESSION_KEYS) this.expressions[key] = advanceExpression(this.expressions[key], now, this.rng, gapFor(key));
   }
 
   /** One interval, retimed when work starts or stops or an expression plays. */
   private retime(now: number): void {
-    const delay = expressionTickDelay(Object.values(this.expressions), now, isLive());
+    const delay = expressionTickDelay(Object.values(this.expressions), now, isLive(), talkFrame(oracleSpokeAt, now) !== undefined);
     if (delay === this.delay) return;
     this.delay = delay;
     clearInterval(this.timer);
     this.timer = setInterval(() => this.advance(), delay);
   }
 
+  private motion(now: number): OracleMotion {
+    return { phase: expressionPhase(this.expressions.oracle, now), talk: talkFrame(oracleSpokeAt, now) };
+  }
+
   private frames(): Partial<Record<ExpressionKey, number>> {
     return Object.fromEntries(EXPRESSION_KEYS.map((key) => [key, this.expressions[key].frame]));
   }
@@ -207,9 +234,10 @@ class ZenWidget implements Component {
     const expressions = this.frames();
     const quiet = isQuiet();
     const frameKey = EXPRESSION_KEYS.map((key) => expressions[key] ?? 0).join(",");
-    const key = `${width}|${rows}|${this.tick}|${frameKey}|${zenVersion}|${Math.floor(now / 1000)}|${quiet}`;
+    const motion = this.motion(now);
+    const key = `${width}|${rows}|${this.tick}|${frameKey}|${motion.phase}|${motion.talk}|${zenVersion}|${Math.floor(now / 1000)}|${quiet}`;
     if (this.cache && this.cache.key === key && this.cache.theme === theme) return this.cache.lines;
-    const opts = { width, rows, tick: this.tick, theme, expressions, oracleActivity };
+    const opts = { width, rows, tick: this.tick, theme, expressions, oracleActivity, oracleMotion: motion };
     const lines = panelLines(zenState.task, zenState.runs, now, quiet, opts).map((line) => truncateToWidth(line, width));
     this.cache = { key, theme, lines };
     return lines;

package/src/pi/zen-large.ts

@@ -2,11 +2,26 @@ import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import {
   BAR,
   BUBBLE,
+  CLOSED_EYE,
+  EYE_WIDTH,
+  GAZE_AHEAD,
+  OPEN_EYE,
   ORACLE_AURA,
   ORACLE_AURA_TICKS,
+  ORACLE_BLINK,
+  ORACLE_BLINKS,
   ORACLE_COLORS,
-  ORACLE_IDLE_WORD,
   ORACLE_FRAMES,
+  ORACLE_GAZE_TICKS,
+  ORACLE_IDLE_WORD,
+  ORACLE_LOOK,
+  ORACLE_LOOK_PATH,
+  ORACLE_MOOD_MOUTHS,
+  ORACLE_PUPILS,
+  ORACLE_REST,
+  ORACLE_TALK,
+  ORACLE_WANDER,
+  ORACLE_WANDER_TICKS,
   ORACLE_WORDS,
   SLOT_FRAMES,
   SLOT_LABELS,
@@ -17,7 +32,9 @@ import {
   TOWER,
   TOWER_DOOR,
   TOWER_WIDTH,
+  type Gaze,
   type OracleFrame,
+  type OracleMood,
   type OraclePose,
   type PanelColor,
   type SlotId,
@@ -63,6 +80,17 @@ export interface LargeTaskRow {
   status: "done" | "current" | "pending";
 }
 
+/** The oracle's pose plus the caller-clocked animation state (see expressions.ts). */
+export interface OracleInput {
+  pose: OraclePose;
+  /** Expression frame: rest, blink, glance or delight (snore while dormant). */
+  frame: number;
+  /** Sub-step inside the playing expression; steps the blink lids and the glance. */
+  phase?: number;
+  /** Lip-sync shape index while the oracle talks about something it just said. */
+  talk?: number;
+}
+
 /** Everything the large scene draws; assembled by the caller from task and runs. */
 export interface LargeSceneInput {
   taskId: string;
@@ -76,7 +104,7 @@ export interface LargeSceneInput {
   total: number;
   slots: readonly LargeSlot[];
   tasks: readonly LargeTaskRow[];
-  oracle: { pose: OraclePose; frame: number };
+  oracle: OracleInput;
   /** Master's live activity for the speech bubble; absent means it waits on the user. */
   oracleActivity?: string;
   /** Plain-words task phase ("writing the plan"); the bubble's fallback second line. */
@@ -310,26 +338,98 @@ function oracleFrame(input: LargeSceneInput): OracleFrame {
   return frames[mod(input.oracle.frame, frames.length)]!;
 }
 
+function frameIndex(input: LargeSceneInput): number {
+  return mod(input.oracle.frame, ORACLE_FRAMES[input.oracle.pose].length);
+}
+
+function phaseOf(input: LargeSceneInput): number {
+  const phase = input.oracle.phase ?? 0;
+  return Number.isFinite(phase) && phase > 0 ? Math.floor(phase) : 0;
+}
+
+/** The oracle's resting mood: worried by a blocker, otherwise steady. */
+export function oracleMood(input: LargeSceneInput): OracleMood {
+  return input.alert && input.alertKind === "error" ? "worried" : "steady";
+}
+
+function isLooking(input: LargeSceneInput): boolean {
+  return frameIndex(input) >= ORACLE_LOOK;
+}
+
+/**
+ * Where the pupils look. The look-around emote scans the room; while talking the
+ * oracle looks at you; while agents work it looks down at them, moving on to
+ * the next one every `ORACLE_GAZE_TICKS`; otherwise its eyes wander the room.
+ */
+export function oracleGaze(input: LargeSceneInput): Gaze {
+  if (input.oracle.pose !== "orchestrating") return GAZE_AHEAD;
+  if (isLooking(input)) return ORACLE_LOOK_PATH[Math.min(phaseOf(input), ORACLE_LOOK_PATH.length - 1)]!;
+  if (input.oracle.talk !== undefined) return GAZE_AHEAD;
+  const working = input.slots.flatMap((slot, index) => (slot.status === "working" ? [index] : []));
+  if (working.length === 0) return ORACLE_WANDER[mod(Math.floor(input.tick / ORACLE_WANDER_TICKS), ORACLE_WANDER.length)]!;
+  const target = working[mod(Math.floor(input.tick / ORACLE_GAZE_TICKS), working.length)]!;
+  const centre = (input.slots.length - 1) / 2;
+  return { x: target < centre ? -1 : target > centre ? 1 : 0, y: 1 };
+}
+
+/** One eye window: a lid fills it, otherwise the pupil sits at the gaze column. */
+function eyeCell(pupil: string, gaze: Gaze): string {
+  if (pupil === CLOSED_EYE) return CLOSED_EYE.repeat(EYE_WIDTH);
+  const glyph = pupil === OPEN_EYE ? ORACLE_PUPILS[gaze.y] : pupil;
+  const at = Math.floor(EYE_WIDTH / 2) + gaze.x;
+  return Array.from({ length: EYE_WIDTH }, (_value, column) => (column === at ? glyph : " ")).join("");
+}
+
+/** Both pupils: blink lids step with the phase, the frame supplies the rest. */
+function oraclePupils(input: LargeSceneInput): readonly [string, string] {
+  if (frameIndex(input) === ORACLE_BLINK) {
+    const lids = ORACLE_BLINKS[input.oracle.pose];
+    return lids[Math.min(phaseOf(input), lids.length - 1)]!;
+  }
+  const frame = oracleFrame(input);
+  return [frame.winL, frame.winR];
+}
+
+/** The mouth: lip-sync while talking, the mood's straight line or frown otherwise; dormant it snores. */
+function oracleMouth(input: LargeSceneInput): string {
+  if (input.oracle.pose !== "orchestrating") return oracleFrame(input).mouth;
+  if (input.oracle.talk !== undefined) return ORACLE_TALK[mod(input.oracle.talk, ORACLE_TALK.length)]!;
+  return ORACLE_MOOD_MOUTHS[oracleMood(input)];
+}
+
+/** The whole face for this frame: orb, both eye windows (three columns each) and the mouth. */
+export function oracleFace(input: LargeSceneInput): { orb: string; left: string; right: string; mouth: string } {
+  const [left, right] = oraclePupils(input);
+  const gaze = oracleGaze(input);
+  return { orb: oracleFrame(input).orb, left: eyeCell(left, gaze), right: eyeCell(right, gaze), mouth: oracleMouth(input) };
+}
+
 function oracleAura(input: LargeSceneInput): string {
   const frames = ORACLE_AURA[input.oracle.pose];
   return frames[mod(Math.floor(input.tick / ORACLE_AURA_TICKS), frames.length)]!;
 }
 
-function towerRow(row: string, input: LargeSceneInput, theme?: PanelTheme): string {
-  const frame = oracleFrame(input);
+/** Painted token values for one frame; built once and shared by every tower row. */
+type TowerValues = ReadonlyMap<string, string>;
+
+function towerValues(input: LargeSceneInput, theme?: PanelTheme): TowerValues {
+  const face = oracleFace(input);
   const accent = ORACLE_COLORS[input.oracle.pose];
   const glow = (text: string) => paint(text, accent.color, theme, accent.bold);
-  const values = new Map<string, () => string>([
-    [TOWER.tokens.aura, () => paint(oracleAura(input), accent.color, theme)],
-    [TOWER.tokens.orb, () => glow(frame.orb)],
-    [TOWER.tokens.winL, () => glow(frame.winL)],
-    [TOWER.tokens.winR, () => glow(frame.winR)],
-    [TOWER.tokens.mouth, () => glow(frame.mouth)],
-    [TOWER.tokens.door, () => glow(input.doorLabel ?? TOWER_DOOR)],
+  return new Map([
+    [TOWER.tokens.aura, paint(oracleAura(input), accent.color, theme)],
+    [TOWER.tokens.orb, glow(face.orb)],
+    [TOWER.tokens.winL, glow(face.left)],
+    [TOWER.tokens.winR, glow(face.right)],
+    [TOWER.tokens.mouth, glow(face.mouth)],
+    [TOWER.tokens.door, glow(input.doorLabel ?? TOWER_DOOR)],
   ]);
+}
+
+function towerRow(row: string, values: TowerValues, theme?: PanelTheme): string {
   return row
     .split(TOWER_PATTERN)
-    .map((part) => values.get(part)?.() ?? paint(part, "muted", theme))
+    .map((part) => values.get(part) ?? paint(part, "muted", theme))
     .join("");
 }
 
@@ -384,23 +484,24 @@ function bubbleStart(rows: readonly string[]): number {
  * The tail from the oracle to the bubble: the tower row's trailing blanks plus
  * the one-column gap become `╶──` (`──(◉)── ╶──┤`); a full-width row gets a stub.
  */
-function tailRow(row: string, input: LargeSceneInput, theme?: PanelTheme): string {
+function tailRow(row: string, values: TowerValues, theme?: PanelTheme): string {
   const body = row.replace(/ +$/, "");
   const pad = row.length - body.length;
   const tail = pad >= 1 ? ` ╶${"─".repeat(pad - 1)}` : "╶";
-  return towerRow(body, input, theme) + paint(tail, "muted", theme);
+  return towerRow(body, values, theme) + paint(tail, "muted", theme);
 }
 
 function towerLines(input: LargeSceneInput, width: number, theme: PanelTheme | undefined, size: TowerSize): string[] {
   if (size === "none") return [];
   const rows = size === "small" ? TOWER.smallRows : TOWER.rows;
   const left = " ".repeat(sceneLeft(width) + Math.floor((SCENE_WIDTH - TOWER_WIDTH) / 2));
+  const values = towerValues(input, theme);
   const bubble = bubbleRows(input, theme);
   const start = bubbleStart(rows);
   return rows.map((row, index) => {
     const speech = bubble[index - start];
-    if (speech === undefined) return left + towerRow(row, input, theme);
-    const tower = index === start + 1 ? tailRow(row, input, theme) : `${towerRow(row, input, theme)} `;
+    if (speech === undefined) return left + towerRow(row, values, theme);
+    const tower = index === start + 1 ? tailRow(row, values, theme) : `${towerRow(row, values, theme)} `;
     return left + tower + speech;
   });
 }

package/src/pi/zen.ts

@@ -537,9 +537,9 @@ function sceneSlots(metrics: SceneMetrics, expressions: ExpressionFrames): Large
   }));
 }
 
-function oracleSlot(task: Task, expressions: ExpressionFrames): LargeSceneInput["oracle"] {
+function oracleSlot(task: Task, expressions: ExpressionFrames, motion: OracleMotion): LargeSceneInput["oracle"] {
   const pose = oraclePose(task);
-  return { pose, frame: expressions.oracle ?? REST_FRAME };
+  return { pose, frame: expressions.oracle ?? REST_FRAME, ...motion };
 }
 
 function sceneTasks(steps: readonly PlanStep[]): LargeTaskRow[] {
@@ -556,8 +556,7 @@ function sceneInput(
   quiet: boolean,
   tick: number,
   steps: PlanStep[],
-  expressions: ExpressionFrames,
-  oracleActivity: string | undefined,
+  opts: PanelOptions,
 ): LargeSceneInput {
   const metrics = sceneMetrics(task, runs, now);
   const alert = taskAlert(task);
@@ -570,10 +569,10 @@ function sceneInput(
     tick,
     done: metrics.done,
     total: metrics.total,
-    slots: sceneSlots(metrics, expressions),
+    slots: sceneSlots(metrics, opts.expressions ?? {}),
     tasks: sceneTasks(steps),
-    oracle: oracleSlot(task, expressions),
-    oracleActivity,
+    oracle: oracleSlot(task, opts.expressions ?? {}, opts.oracleMotion ?? {}),
+    oracleActivity: opts.oracleActivity,
     caption: task.paused ? "task paused" : SCENE_PROPS[task.state],
     alert: alert?.text,
     alertKind: alert?.kind,
@@ -591,6 +590,14 @@ export interface PanelOptions {
   expressions?: ExpressionFrames;
   /** Live master activity word for the oracle's speech bubble; absent means it waits on the user. */
   oracleActivity?: string;
+  /** Caller-clocked oracle animation: the expression's sub-step and the lip-sync shape. */
+  oracleMotion?: OracleMotion;
+}
+
+/** The oracle's clocked animation state beyond its expression frame (see expressions.ts). */
+export interface OracleMotion {
+  phase?: number;
+  talk?: number;
 }
 
 /**
@@ -613,7 +620,7 @@ export function panelLines(
   const steps = planChecklist(task.plan ?? "", runs);
   const budget = largeLineBudget(opts.rows ?? DEFAULT_ROWS);
   if (width >= LARGE_MIN_WIDTH && budget >= MIN_LARGE_LINES) {
-    const scene = largeLines(sceneInput(task, runs, now, quiet, tick, steps, opts.expressions ?? {}, opts.oracleActivity), width, budget, opts.theme);
+    const scene = largeLines(sceneInput(task, runs, now, quiet, tick, steps, opts), width, budget, opts.theme);
     return scene.map((line) => truncateToWidth(line, width));
   }
   return compactPanel(task, runs, now, quiet, tick, steps, opts, width);