### Environment Configuration Example

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/specs/2026-03-04-sqlalchemy-orm-migration-design.md

Example configuration for database connection strings in .env files.

```bash
# 数据库配置（默认使用 SQLite）
# SQLite（开发/单机）: sqlite+aiosqlite:///./projects/.arcreel.db
# PostgreSQL（生产）:  postgresql+asyncpg://user:pass@host:5432/arcreel
# DATABASE_URL=sqlite+aiosqlite:///./projects/.arcreel.db
```

--------------------------------

### Start WebUI Server

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/plans/2026-02-05-character-reference-image-impl.md

Command to start the WebUI server for integration testing.

```bash
cd /Users/pollochen/Documents/ai-anime/.worktrees/character-reference-image && python -m webui.server.main &
```

--------------------------------

### Frontend Development Server Start Command

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/plans/2026-03-10-segment-note-impl.md

Command to start the frontend development server.

```bash
cd frontend && pnpm dev
```

--------------------------------

### Start Backend Dev Server

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/plans/2026-04-17-reference-to-video-pr5-frontend-editor.md

Command to start the backend development server with Uvicorn.

```bash
uv run python -m uvicorn server.app:app --reload --port 1241
```

--------------------------------

### Start Development Servers

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/plans/2026-03-31-custom-provider.md

Launch the backend development server with hot-reloading and the frontend development server.

```bash
uv run uvicorn server.app:app --reload --port 1241 &
cd frontend && pnpm dev
```

--------------------------------

### Start development server

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/plans/2026-05-07-sdk-0.1.76-upgrade.md

Command to start the development server for end-to-end testing.

```bash
uv run uvicorn server.app:app --reload --reload-dir server --reload-dir lib --port 1241
```

--------------------------------

### Step 3: Start Server and Run Smoke Test

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/plans/2026-04-20-source-format-support-expansion.md

Starts the uvicorn server, performs a health check, and then stops the server.

```bash
uv run uvicorn server.app:app --port 1241 &
SERVER_PID=$!
sleep 5
curl -s http://127.0.0.1:1241/health | jq .
kill $SERVER_PID
```

--------------------------------

### Development Server Startup Commands

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/plans/2026-03-23-jianying-draft-export.md

Commands to start the backend and frontend development servers for manual verification.

```bash
uv run uvicorn server.app:app --reload --port 1241
cd frontend && pnpm dev
```

--------------------------------

### Example Prompt Input

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/plans/2026-04-17-reference-to-video-pr5-frontend-editor.md

Example of inputting a prompt in the editor, triggering the MentionPicker.

```text
Shot 1 (3s): 主角推门进入 @
```

--------------------------------

### Start server for sync verification

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/plans/2026-05-16-dynamic-agent-profile.md

Command to start the uvicorn server with hot-reloading for server and lib directories.

```bash
uv run uvicorn server.app:app --reload-dir server --reload-dir lib --port 1241
```

--------------------------------

### Example Generate Video Request

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/plans/2026-04-17-reference-to-video-pr5-frontend-editor.md

Example of initiating video generation via a POST request.

```bash
POST .../generate
```

--------------------------------

### 首尾帧生视频 API 请求示例

Source: https://github.com/arcreel/arcreel/blob/main/docs/vidu-docs/首尾帧生视频.md

This example demonstrates how to make a POST request to the start-end2video API to generate a video from start and end frames.

```bash
curl -X POST -H "Authorization: Token {your_api_key}" -H "Content-Type: application/json" -d \
{
    "model": "viduq3-pro",
    "images": ["https://prod-ss-images.s3.cn-northwest-1.amazonaws.com.cn/vidu-maas/template/startend2video-1.jpeg","https://prod-ss-images.s3.cn-northwest-1.amazonaws.com.cn/vidu-maas/template/startend2video-2.jpeg"],
    "prompt": "The camera zooms in on the bird, which then flies to the right. With its flight being smooth and natural, the bird soars in the sky. with a red light effect following and surrounding it from behind.",
    "duration": 5,
    "seed": 0,
    "resolution": "1080p",
    "audio": true,
    "off_peak": false
}' https://api.vidu.cn/ent/v2/start-end2video
```

--------------------------------

### Startup Failure Exit Information (Structured)

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/specs/2026-05-12-agent-sandbox-design.md

Example structured output for sandbox unavailability errors on Linux, including installation instructions for bubblewrap.

```text
SANDBOX_UNAVAILABLE on linux
  sandbox-exec: n/a (not macOS)
  bwrap:        not found in PATH
Required for ArcReel agent runtime. Install bubblewrap:
  Ubuntu/Debian: sudo apt install bubblewrap
  Arch:          sudo pacman -S bubblewrap
```

--------------------------------

### Step 2: Full Frontend Test + Build

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/plans/2026-04-20-source-format-support-expansion.md

Navigates to the frontend directory, runs checks, and builds the project.

```bash
cd frontend && pnpm check && pnpm build
cd ..
```

--------------------------------

### Update .env.example Configuration

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/plans/2026-03-16-video-service-layer.md

Append these configuration keys to your .env.example file to support Seedance video provider integration.

```bash
# === 视频供应商 ===
# DEFAULT_VIDEO_PROVIDER=gemini     # 全局默认视频供应商 (gemini | seedance)

# === Seedance (火山方舟) ===
# ARK_API_KEY=                      # 火山方舟 API key
# FILE_SERVICE_BASE_URL=            # 项目文件服务公网地址 (Seedance 图片上传需要公网访问)
```

--------------------------------

### Backend Server Start Command

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/plans/2026-03-10-segment-note-impl.md

Command to start the backend server with hot-reloading.

```bash
uv run uvicorn server.app:app --reload --port 1241
```

--------------------------------

### Step 1: Run Frontend Build Verification

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/plans/2026-02-10-assistant-question-wizard-impl.md

Command to execute the frontend build process and verify for syntax errors.

```bash
npm --prefix frontend run build
```

--------------------------------

### Example API Request

Source: https://github.com/arcreel/arcreel/blob/main/docs/vidu-docs/参考生视频.md

This is an example of a cURL request to the API for generating a video.

```bash
curl -X POST -H "Authorization: Token {your_api_key}" -H "Content-Type: application/json" -d \
{
    "model": "viduq3-mix",
    "images": ["https://prod-ss-images.s3.cn-northwest-1.amazonaws.com.cn/vidu-maas/template/reference2video-1.png","https://prod-ss-images.s3.cn-northwest-1.amazonaws.com.cn/vidu-maas/template/reference2video-2.png","https://prod-ss-images.s3.cn-northwest-1.amazonaws.com.cn/vidu-maas/template/reference2video-3.png"],
    "prompt": "Santa Claus and the bear hug by the lakeside.",
    "duration": 5,
    "seed": 0,
    "aspect_ratio": "3:4",
    "resolution": "720p",

```

--------------------------------

### Self-Check Application Startup

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/plans/2026-04-17-reference-to-video-pr3-backend.md

Command to verify the mounted routes for reference videos.

```bash
uv run python -c "from server.app import app; [print(r.path) for r in app.routes if 'reference-videos' in getattr(r, 'path', '')]"
```

--------------------------------

### Request Body Example

Source: https://github.com/arcreel/arcreel/blob/main/docs/vidu-docs/参考生视频.md

Example of the request body structure for the Reference Video API.

```json
{
  "video_url": "string",
  "video_id": "string",
  "video_file": "string"
}
```

--------------------------------

### Commit Message Examples

Source: https://github.com/arcreel/arcreel/blob/main/CONTRIBUTING.md

Examples of standard commits including scope, descriptions, and body text.

```text
# 新功能（minor bump）
feat(image-backends): 支持 OpenAI DALL-E 3 后端

# Bug 修复（patch bump）
fix(queue): 修复任务 lease 超时后未正确归还的问题

# 带 scope 与正文
feat(grid): 支持 grid_12 布局

将宫格系统扩展到 12 宫格，适用于长篇剧集的批量预览。
```

--------------------------------

### Run Tests

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/plans/2026-04-06-video-duration-selection.md

Commands to run tests to confirm the changes.

```bash
Run: `uv run python -m pytest tests/test_prompt_builders.py tests/test_prompt_builders_script.py -v`
Expected: ALL PASS

Run: `uv run python -m pytest -x`
Expected: PASS
```

--------------------------------

### Package Initialization (`__init__.py`)

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/plans/2026-04-17-reference-to-video-pr2-data-model.md

Initializes the `reference_video` package by importing and exporting the `parse_prompt` and `render_prompt_for_backend` functions.

```python
from lib.reference_video.shot_parser import parse_prompt, render_prompt_for_backend

__all__ = ["parse_prompt", "render_prompt_for_backend"]
```

--------------------------------

### Start Backend Service

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/plans/2026-02-09-sdk-client-migration.md

Command to start the backend Uvicorn server for development.

```bash
# 终端 1: 启动后端
cd webui && python -m uvicorn server.main:app --reload --port 8000
```

--------------------------------

### Video Generation Response Example

Source: https://github.com/arcreel/arcreel/blob/main/docs/vidu-docs/参考生视频.md

An example of the JSON response body for a video generation task.

```json
{
  "task_id": "your_task_id_here",
  "state": "created",
  "model": "viduq3",
  "images": ["your_image_url1","your_image_url2"],
  "prompt": "@1 和 @2 在一起吃火锅，并且旁白音说火锅大家都爱吃。",
  "duration": 8,
  "seed": 0,
  "aspect_ratio": "3:4",
  "resolution": "1080p",
  "movement_amplitude": "auto",
  "payload":"",
  "off_peak": false,
  "credits": 12,
  "created_at": "2025-01-01T15:41:31.968916Z"
}
```

--------------------------------

### Verify Dependencies and Run Tests

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/plans/2026-03-16-video-service-layer.md

Commands to synchronize dependencies, verify the SDK installation, and execute the test suite.

```bash
uv sync && python -c "from volcenginesdkarkruntime import Ark; print('ok')"
```

```bash
python -m pytest -x -q
```

--------------------------------

### Step 3: Implement run_with_backend + Main Wiring

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/plans/2026-04-17-reference-to-video-pr1-sdk-verification.md

Edit `scripts/verify_reference_video_sdks.py` to implement the `run_with_backend` function and wire it with `main`. Remove the old placeholder `main` function.

```python
import asyncio
from datetime import date


async def run_with_backend(
    *,
    provider: Provider,
    refs: int,
    duration: int,
    multi_shot: bool,
    report_dir: Path,
    work_dir: Path,
) -> int:
    backend = resolve_backend(provider)
    clamped, note = clamp_refs_for_backend(
        requested=refs,
        caps=backend.video_capabilities,
    )
    result = await run_once(
        provider=provider,
        backend=backend,
        refs=clamped,
        duration=duration,
        multi_shot=multi_shot,
        work_dir=work_dir,
    )
    if note:
        result.note = note
    report_dir.mkdir(parents=True, exist_ok=True)
    fname = report_dir / f"reference-video-sdks-{date.today():%Y-%m-%d}.md"
    # 多次运行追加模式：读原文件剥离 header、合并行
    existing_rows: list[str] = []
    if fname.exists():
        existing = fname.read_text(encoding="utf-8").splitlines()
        existing_rows = [ln for ln in existing if ln.startswith("| ") and "Provider" not in ln and "---" not in ln]
    md = render_report([result])
    if existing_rows:
        lines = md.splitlines()
        # 把已有数据行塞回表尾
        lines.extend(existing_rows)
        md = "\n".join(lines) + "\n"
    fname.write_text(md, encoding="utf-8")
    return 0 if result.success else 2


def main() -> int:
    args = parse_args()
    work_dir = Path(".verify_work") / args.provider
    return asyncio.run(run_with_backend(
        provider=args.provider,
        refs=args.refs,
        duration=args.duration,
        multi_shot=args.multi_shot,
        report_dir=args.report_dir,
        work_dir=work_dir,
    ))
```

--------------------------------

### Start Frontend Service

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/plans/2026-02-09-sdk-client-migration.md

Command to start the frontend development server using pnpm.

```bash
# 终端 2: 启动前端
cd frontend && pnpm dev
```

--------------------------------

### Response Body Example

Source: https://github.com/arcreel/arcreel/blob/main/docs/vidu-docs/文生视频.md

An example of the JSON response body returned after a video generation task is submitted.

```json
{
  "task_id": "your_task_id_here",
  "state": "created",
  "model": "viduq3-pro",
  "style": "general",
  "prompt": "In an ultra-realistic fashion photography style featuring light blue and pale amber tones, an astronaut in a spacesuit walks through the fog. The background consists of enchanting white and golden lights, creating a minimalist still life and an impressive panoramic scene.",
  "duration": 5,
  "seed": 0,
  "aspect_ratio": "4:3",
  "resolution": "540p",
  "movement_amplitude": "auto",
  "payload": "",
  "off_peak": false,
  "credits": 12,
  "created_at": "2025-01-01T15:41:31.968916Z"
}
```

--------------------------------

### Git Commit Example

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/plans/2026-04-17-reference-to-video-pr6-agent-workflow.md

Example of adding and committing the split-reference-video-units subagent.

```bash
git add agent_runtime_profile/.claude/agents/split-reference-video-units.md
git commit -m "feat(agent): add split-reference-video-units subagent (PR6)"

```

--------------------------------

### Create GeminiVideoBackend Test

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/plans/2026-03-16-video-service-layer.md

Initializes the test file for the GeminiVideoBackend, setting up the testing environment.

```python
class TestGeminiVideoBackend:
    pass
```

--------------------------------

### Reference Video API Response Example

Source: https://github.com/arcreel/arcreel/blob/main/docs/vidu-docs/参考生视频.md

An example JSON object representing the response from the Reference Video API.

```json
{
  "task_id": "your_task_id_here",
  "state": "created",
  "model": "viduq3-mix",
  "images": ["https://prod-ss-images.s3.cn-northwest-1.amazonaws.com.cn/vidu-maas/template/reference2video-1.png","https://prod-ss-images.s3.cn-northwest-1.amazonaws.com.cn/vidu-maas/template/reference2video-2.png","https://prod-ss-images.s3.cn-northwest-1.amazonaws.com.cn/vidu-maas/template/reference2video-3.png"],
  "prompt": "Santa Claus and the bear hug by the lakeside.",
  "duration": 5,
  "seed": 0,
  "aspect_ratio": "3:4",
  "resolution": "720p",
  "credits": 12,
  "created_at": "2025-01-01T15:41:31.968916Z"
}
```

--------------------------------

### Command to run tests

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/plans/2026-04-23-resolution-param-refactor.md

Command to execute the tests for the GrokImageBackend image resolution logic.

```bash
uv run python -m pytest tests/lib/image_backends/test_grok_image_resolution.py -v
```

--------------------------------

### Step 2: Run Tests to Verify Failure

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/plans/2026-03-06-agent-runtime-isolation-plan.md

Command to run the newly created tests.

```bash
python -m pytest tests/test_project_manager_symlink.py -v
```

--------------------------------

### frontend/src/hooks/useProjectEventsSSE.ts Example

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/specs/2026-04-14-eslint-a11y-pr3-design.md

Example of using discriminated unions for SSE payloads in frontend/src/hooks/useProjectEventsSSE.ts.

```typescript
type ProjectEvent =
  | { type: "project_updated"; project_name: string }
  | { type: "task_status"; task_id: string; status: string }
  | ...;
```

--------------------------------

### Dependency Installation Command

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/specs/2026-04-20-source-format-support-expansion-design.md

Command to add necessary Python dependencies using uv.

```bash
uv add charset-normalizer docx2txt mammoth ebooklib beautifulsoup4 lxml pdf-oxide
```

--------------------------------

### frontend/src/api/auth.ts Example

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/specs/2026-04-14-eslint-a11y-pr3-design.md

Example of adding types to the login response and handling errors in frontend/src/api/auth.ts.

```typescript
interface LoginResponse { access_token: string; token_type: string }
interface ErrorResponse { detail: string }

export async function login(...): Promise<LoginResponse> { ... }
```

--------------------------------

### Step 5: Placeholder for `docs/verification-reports/` + Commit

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/plans/2026-04-17-reference-to-video-pr1-sdk-verification.md

Create a placeholder directory and file for verification reports, then add and commit the changes.

```bash
mkdir -p docs/verification-reports
touch docs/verification-reports/.gitkeep
git add scripts/verify_reference_video_sdks.py tests/scripts/test_verify_reference_video_sdks.py docs/verification-reports/.gitkeep
git commit -m "feat(sdk-verify): wire main() end-to-end with append-mode report"
```

--------------------------------

### Example Reference Payload

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/plans/2026-04-17-reference-to-video-pr5-frontend-editor.md

Example of the PATCH request body containing prompt and references.

```json
{
  "prompt": "Shot 1 (3s): 主角推门进入 @主角 @酒馆 @长剑",
  "references": [
    { "character": "主角" },
    { "scene": "酒馆" },
    { "prop": "长剑" }
  ]
}
```

--------------------------------

### Commit App Startup Migration Changes

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/plans/2026-04-15-global-asset-library.md

Git commands to add and commit changes for app startup migration.

```bash
git add server/app.py tests/test_app_startup_migration.py
git commit -m "feat(app): 启动时自动跑项目迁移 + 7 天备份清理"
```

--------------------------------

### Test Startup Invokes Migrations

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/plans/2026-04-15-global-asset-library.md

Python code for testing if run_project_migrations is called on FastAPI startup.

```python
"""FastAPI 启动时调用 run_project_migrations。"""
from unittest.mock import patch

import pytest


@pytest.mark.asyncio
async def test_startup_invokes_migrations(tmp_path, monkeypatch):
    monkeypatch.setenv("ARCREEL_PROJECTS_DIR", str(tmp_path))

    with patch("lib.project_migrations.run_project_migrations") as mock_run, \
         patch("lib.project_migrations.cleanup_stale_backups") as mock_cleanup:
        from server.app import app

        async with app.router.lifespan_context(app):
            pass

        mock_run.assert_called_once()
        mock_cleanup.assert_called_once()

```

--------------------------------

### Manual Smoke Test Steps

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/plans/2026-04-23-resolution-param-refactor.md

Starts the development environment for both backend and frontend, and outlines key user flows to test.

```bash
uv run python -m uvicorn server.main:app --port 1241 --reload
cd frontend && pnpm dev
```

--------------------------------

### Create Text Backend for Task

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/plans/2026-03-31-custom-provider.md

Initializes a text backend based on the task type, supporting custom provider paths via the CustomProviderRepository.

```python
async def create_text_backend_for_task(task_type, project_name=None):
    resolver = ConfigResolver(async_session_factory)
    provider_id, model_id = await resolver.text_backend_for_task(task_type, project_name)
    
    # 自定义供应商走独立路径
    if provider_id.startswith("custom-"):
        from lib.custom_provider.factory import create_custom_backend
        from lib.db import async_session_factory as sf
        from lib.db.repositories.custom_provider_repo import CustomProviderRepository
        async with sf() as session:
            repo = CustomProviderRepository(session)
            db_id = int(provider_id.removeprefix("custom-"))
            provider = await repo.get_provider(db_id)
            if provider is None:
                raise ValueError(f"自定义供应商 {provider_id} 不存在")
            return create_custom_backend(provider=provider, model_id=model_id, media_type="text")

    # ... 现有预置供应商逻辑 ...
```

--------------------------------

### Start Patrol Task in SessionManager

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/plans/2026-03-23-session-memory-leak-fix.md

Adds the `start_patrol` method to `SessionManager`. This method is responsible for creating and starting the background patrol task, typically called during application startup.

```python
    def start_patrol(self) -> None:
        """启动巡检后台任务（应在应用 startup 时调用）。"""
        self._patrol_task = asyncio.create_task(self._patrol_loop())
```

--------------------------------

### Step 2: 改 _baseline_env（行 228）

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/plans/2026-05-12-agent-sandbox.md

__init__ 中删除 _baseline_env 字段创建

```python
self._baseline_env: dict[str, str | None] = {}
```

--------------------------------

### frontend/src/api/tasks.ts and useTasksSSE.ts Example

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/specs/2026-04-14-eslint-a11y-pr3-design.md

Example of adding types to SSE payloads and using runtime type guards in frontend/src/api/tasks.ts and useTasksSSE.ts.

```typescript
interface TaskEvent { type: "stats"; stats: TaskStats }
// 解析：JSON.parse(e.data) as TaskEvent + runtime type guard（校验 type 字段）
```

--------------------------------

### Run Full Frontend Tests and Build

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/plans/2026-05-04-video-duration-redesign.md

Runs frontend type checking, tests, and build process.

```bash
cd frontend && pnpm check  # = typecheck + test
```

```bash
cd frontend && pnpm build
```

--------------------------------

### SDK Conformance Test Example

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/specs/2026-05-01-sdk-session-store-design.md

Example of how to run SDK session store conformance tests using the provided testing utility.

```python
tests/agent_session_store/test_conformance.py
from claude_agent_sdk.testing import \
    run_session_store_conformance
await run_session_store_conformance(make_store)
```

--------------------------------

### Project-Specific Unit Test Example

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/specs/2026-05-01-sdk-session-store-design.md

Example of a project-specific unit test for session store functionality, specifically testing concurrent appends to the same session.

```python
test_seq_concurrency.py: 同 session 并发 append
→ 全部成功 + seq 连续 + 无重复 uuid
```

--------------------------------

### Step 4: Run Full Tests

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/plans/2026-05-02-agent-custom-provider.md

Commands to run all backend and frontend tests.

```bash
uv run python -m pytest -q
cd frontend && pnpm check
```

--------------------------------

### Run Test for App Startup Migration

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/plans/2026-04-15-global-asset-library.md

Command to run pytest for the app startup migration test.

```bash
uv run python -m pytest tests/test_app_startup_migration.py -v
```

--------------------------------

### Test for SessionActor start and connect

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/plans/2026-04-13-session-actor.md

This Python code snippet adds a test to verify that SessionActor starts and connects successfully to a fake client, and handles disconnection.

```python
def _collect(messages: list, managed_on_message):
    """辅助：on_message 把消息追加到外部列表。"""
    def _on(msg: dict) -> None: 
        messages.append(msg)
    return _on


@pytest.mark.asyncio
async def test_actor_start_connects_fake_client():
    client = FakeSDKClient()
    actor = SessionActor(
        client_factory=lambda: client,
        on_message=lambda msg: None,
    )
    await actor.start()
    assert actor._started.is_set()
    assert "connect" in client.method_tasks
    # 立即发 disconnect 把 actor 收尾
    cmd = SessionCommand(type="disconnect")
    await actor.enqueue(cmd)
    await cmd.done.wait()
    if actor._task is not None:
        await actor._task
    assert client.disconnected


@pytest.mark.asyncio
async def test_actor_start_propagates_connect_failure():
    client = FakeSDKClient(connect_error=RuntimeError("boom"))
    actor = SessionActor(
        client_factory=lambda: client,
        on_message=lambda msg: None,
    )
    with pytest.raises(RuntimeError, match="boom"):
        await actor.start()
    assert actor._fatal is not None


@pytest.mark.asyncio
async def test_actor_connect_and_disconnect_same_task():
    client = FakeSDKClient()
    actor = SessionActor(
        client_factory=lambda: client,
        on_message=lambda msg: None,
    )
    await actor.start()
    cmd = SessionCommand(type="disconnect")
    await actor.enqueue(cmd)
    await cmd.done.wait()
    if actor._task is not None:
        await actor._task
    assert client.method_tasks["connect"] == client.method_tasks["disconnect"]
```

--------------------------------

### Running tests

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/plans/2026-04-07-agent-file-type-guard.md

Commands to run specific and full test suites to verify the changes.

```bash
uv run python -m pytest tests/test_session_manager_more.py::TestFileAccessHook -v
```

```bash
uv run python -m pytest tests/test_session_manager_more.py -v
```

--------------------------------

### Media Has Caption Rule Example

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/specs/2026-04-14-eslint-a11y-pr3-design.md

Example of using `eslint-disable-next-line` for the `media-has-caption` rule when dealing with preview videos that currently lack a caption source.

```tsx
{/* eslint-disable-next-line jsx-a11y/media-has-caption -- 生成式预览视频暂无字幕源，将来如引入字幕生成则移除此 disable */}
<video src={...} controls />
```

--------------------------------

### Start server with batched flush for manual acceptance 3

Source: https://github.com/arcreel/arcreel/blob/main/docs/superpowers/plans/2026-05-06-sdk-eager-flush.md

Starts the Uvicorn server with the SDK session store flush set to 'batched'.

```bash
ARCREEL_SDK_SESSION_STORE_FLUSH=batched uv run uvicorn server.app:app --reload-dir server --reload-dir lib --port 1241
```