(CODUX-224) Restore cinematic work-tool lifecycle

[numnx]

🧩 Task: Restore cinematic work-tool lifecycle

Automated task PR opened by Code UX for T02.

📋 Summary

Sprint: Sprint 224 · Repair 3D agent activity feedback · Task: T02

Repair the existing 3D Chat stage so matching active Project Manager invocations drive cycling avatar tools and a transient animated bubble showing the latest eligible invocation assistant message, in-progress status, and unique tool count; improve large-screen response sizing, typography, and thought-to-avatar spacing; and cover lifecycle, reduced-motion, responsive, stale-response, and fetch-failure behavior with dashboard tests and synchronized documentation.

🤖 Model & Provider

Provider	Codex CLI
Model	gpt-5.6-sol

⏱️ Timing

Started	2026-07-13 21:24:37 UTC
Finished	2026-07-13 21:34:05 UTC
Duration	9m 28s

📊 Token Usage

Metric	Value
Input tokens	135,124
Cached input tokens	3,990,016
Output tokens	15,687
Total tokens	4,140,827
Invocations	1
Tool calls	53
Active time	8m 55s

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

✅ 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
Create a reusable cinematic work-tool hook that immediately selects a tool for active invocation work, rotates through the existing tool catalog, and provides a stable reduced-motion fallback.

## Scope
- Create `dashboard/src/v2/components/chat/cinematic/use-cinematic-work-tool.ts`
- Verify and reuse `dashboard/src/v2/lib/agent-scene-tools.ts`, including `AGENT_SCENE_TOOL_IDS` and `isAgentSceneTool`
- Create `tests/dashboard/v2/use-cinematic-work-tool.test.tsx`
- Verify compatibility with `tests/dashboard/v2/agent-scene-tools.test.ts` and `tests/dashboard/v2/agent-avatar-scene-lazy.test.tsx`

## Implementation Requirements
1. Export a typed hook that accepts an explicit active flag, stable activity key, and reduced-motion state instead of independently inferring invocation ownership.
2. Select a deterministic initial tool from `AGENT_SCENE_TOOL_IDS` as soon as the supplied activity becomes active, then rotate without immediate repetition at the established seven-second cadence while the same activity remains active.
3. Preserve the validated `?stageTool=` design-review override, including its precedence over inactive state, and reject unknown tool identifiers through `isAgentSceneTool`.
4. In reduced-motion mode, keep one semantically identifiable static tool without starting a rotation timer; when activity stops or changes, clear or reinitialize state predictably.
5. Clear every interval on deactivation, activity-key changes, override changes, and unmount, and add fake-timer tests for activation, rotation, reduced motion, forced overrides, activity replacement, and cleanup.

## Constraints
- Do not modify `AgentAvatarScene` renderer creation, avatar rebuilds, WebGL lifecycle, geometry, or material disposal behavior.
- Do not install another animation or state-management dependency.
- Keep activity ownership outside this hook so the integration can prevent unrelated background invocations from selecting a Project Manager tool.
- Preserve the existing static tool label and accessible avatar fallback supplied by `LazyAgentAvatarScene` and `AgentAvatarScene`.

## Verification
- Run `pnpm exec vitest run tests/dashboard/v2/use-cinematic-work-tool.test.tsx tests/dashboard/v2/agent-scene-tools.test.ts tests/dashboard/v2/agent-avatar-scene-lazy.test.tsx`.
- Run `pnpm run typecheck:dashboard`.
- Confirm active work selects and rotates tools, reduced motion remains static, invalid overrides are ignored, and no timer survives deactivation or unmount.

🌿 Branch Info

Base: feature/CODUX-224-repair-3d-agent-activity-feedback
Head: task/feature-codux-22-t02-codex-6e494670-mrjqd9ne

---

🤖 Generated by Code UX