(CODUX-111) Add avatar flashlight effect

[numnx]

🧩 Task: Add avatar flashlight effect

Automated task PR opened by Code UX for T04.

📋 Summary

Sprint: Sprint 177 · Status messages, 3d agent enhancement · Task: T04

Make the chat and 3D agent feel like a funny project-manager buddy by adding a large safe humor message catalog, five-second status rotation, tool/thinking jokes, a performant pseudo-raytraced 3D flashlight with low-battery moments, assistant mood asides, tests, and dashboard documentation.

🤖 Model & Provider

Provider	Codex CLI
Model	gpt-5.5

⏱️ Timing

Started	2026-07-07 12:30:50 UTC
Finished	2026-07-07 12:48:06 UTC
Duration	17m 17s

📊 Token Usage

Metric	Value
Input tokens	140,495
Cached input tokens	4,368,896
Output tokens	23,535
Total tokens	4,532,926
Invocations	1
Tool calls	74
Active time	15m 34s

Included usage estimate (subscription/local login): $3.59

✅ QA Review

⏳ QA review runs after this PR is opened. Check the task card in the dashboard for the outcome once it lands.

📝 Full Task Prompt

## Objective
Give the 3D agent avatar an interactive pseudo-raytraced flashlight that sweeps around the scene, brightens what it points at, and rarely flickers with a funny low-battery thought.

## Scope
- `dashboard/src/v2/components/agents/AgentAvatarScene.tsx`
- `dashboard/src/v2/components/agents/LazyAgentAvatarScene.tsx` only if prop typing needs to pass through unchanged behavior
- Create `dashboard/src/v2/lib/agent-flashlight.ts` for deterministic flashlight frame/flicker helpers if needed
- Create `tests/dashboard/lib/agent-flashlight.test.ts` if helper logic is extracted
- Consumes `battery` messages from `dashboard/src/v2/lib/agent-humor-messages.ts`

## Implementation Requirements
1. Add a lightweight flashlight system to `AgentAvatarScene` using standard Three.js lights/materials only: a `SpotLight` or `PointLight`, a translucent cone or projected glow mesh, and accent-aware intensity changes; do not use ray tracing, render targets, post-processing, or per-pixel readbacks.
2. Animate the beam to follow pointer parallax when hovering and gently scan while idle, brightening nearby avatar/background elements through light intensity and material emissive changes.
3. Add a rare low-battery flicker path driven by deterministic helper logic or bounded random scheduling, showing a short `battery` humor line in an absolutely positioned overlay inside the scene.
4. Respect `fallbackMode`, WebGL errors, and reduced-motion: fallback SVG mode should still render, reduced motion should minimize scanning/flicker, and all new geometries/materials/lights must be disposed on unmount.
5. Add focused helper tests for flashlight frame math and low-battery trigger bounds if helper logic is extracted.

## Constraints
- Do not change avatar customization schemas or persisted `AgentAvatarConfig` fields.
- Keep the scene performant on low-power devices: no new dependencies, no real ray tracing, no expensive shadows, and no renderer recreation during animation.
- Do not edit chat bubble status/tool/reasoning components in this task.
- Maintain the existing WebGL context lifecycle split documented in `AgentAvatarScene.tsx`.

## Verification
- Run `pnpm exec vitest run tests/dashboard/lib/agent-flashlight.test.ts tests/dashboard/lib/agent-humor-messages.test.ts` if `agent-flashlight.test.ts` exists; otherwise run `pnpm exec vitest run tests/dashboard/lib/agent-humor-messages.test.ts`.
- Run `pnpm run typecheck:dashboard`.
- Run `pnpm run build:dashboard` for the Three.js bundle path.
- Success means the 3D avatar renders with a nonblank animated flashlight effect, fallback mode still works, and no TypeScript or build errors are introduced.

🌿 Branch Info

Base: feature/CODUX-177-status-messages-3d-agent-enhancement
Head: task/feature-codux-177-status-messages-3d-agent-enhan-t04-codex-mramnpqn

---

🤖 Generated by Code UX