feat: compound start, viewport screenshot, openclaw skill (0.2.8)

[Shadow-Azure]

Problem

Three issues found during v0.2.7 release testing:

1. OpenClaw can't read screenshots. The installed cli-box SKILL.md is identical for every harness, so OpenClaw-driven agents save cli-box screenshot output to the CWD. OpenClaw is sandboxed to /tmp/openclaw/ and cannot read/send those images.
2. Compound start fails. cli-box start "cd /x && claude -r" errors out — the daemon's PTY spawn treats the whole string as the executable name (CommandBuilder::new(command)), so &&, ;, |, and cd are never interpreted.
3. Screenshots show the wrong content. cli-box screenshot on a long claude task returns the oldest lines, not the visible viewport. The renderer's buffer-fallback loop reads buffer.getLine(0..rows) (scrollback top) instead of the viewport (baseY..baseY+rows). There is also no way to scroll the capture window, and no way to dump the whole session.

Solution

1. OpenClaw screenshot path (329d992)

• packages/cli-box-skill/installer/shared.mjs: new targetSpecificNote(id); installSkillToTargets composes readBundledSkill() + targetSpecificNote(id) per target. Only the OpenClaw copy gains a note instructing agents to save screenshots under /tmp/openclaw/. Claude/OpenCode bodies are byte-identical to before.

2. Compound start via shell (e669c5a, e216755)

• crates/cli-box-core/src/process/mod.rs: pure needs_shell + wrap_shell_command + prepare_spawn helpers. When the command contains a space or shell metacharacters, it is re-spawned as zsh -lc "<full line>"; plain commands pass through unchanged. Wired at the top of the macOS spawn_cli_with_size, so CLI/MCP/Electron-new-dialog all benefit. .app paths are unaffected (mode split happens upstream); the displayed command in list/inspect still shows the original (stored separately in InstanceKind).

3. Viewport screenshot + scroll + full-session text

• Renderer buffer-fallback extracted to a pure module anchored at buffer.baseY with a clamped scroll offset (a8cfe45, dca44ce). captureToPng(offset) uses the live xterm canvas only at offset 0, else renders the buffer window.
• Daemon: screenshot?scroll=N|top=true and a new /box/{id}/scrollback route (5bc769c).
• Renderer WS: capture_request.scroll and new scrollback_request/response over the screenshot socket; pure readScrollback text extractor (dc8e1b6).
• CLI: screenshot --up N / --top, new scrollback --id subcommand, plus MCP tools (77eb8ca).
• E2E: tests/e2e-compound-start-screenshot.sh (b9fb981). Polish: dead-code removal + negative-offset guard test (dd80f59). Version 0.2.8 / skill 0.2.2 (5cd9b24).

Spec: docs/superpowers/specs/2026-06-17-start-shell-screenshot-openclaw-design.md
Plan: docs/superpowers/plans/2026-06-17-start-shell-screenshot-openclaw.md

Test Plan

• UT (Rust): needs_shell / wrap_shell_command / prepare_spawn truth table (8 tests)
• UT (JS): installer — OpenClaw body contains /tmp/openclaw/; Claude/OpenCode do not (skill suite 18/18)
• UT (TS): renderBufferToPng viewport(baseY)+offset+clamp+negative (4 tests); readScrollback trim/range/clamp (4 tests); captureToPng background/dimensions migrated to the extracted module
• IT (Rust): /box/{id}/screenshot?scroll=/?top= parse; /box/{id}/scrollback route exists (daemon_integration)
• cargo test / cargo clippy -D warnings / cargo fmt --check / pnpm typecheck / pnpm vitest run — all green
• cli-box screenshot --help shows --up/--top; cli-box scrollback --help shows its options
• Release-build verification (pending sh release.sh + daemon restart): the compound-start E2E needs the rebuilt 0.2.8 daemon on PATH. A stale 0.2.4 release daemon is currently running in this environment, so the live E2E exercised the old spawn path (the 8 unit tests + 2 ITs verify the new logic). After a release rebuild + daemon restart the E2E passes.
• Empirical claude rendering check (pending release testing): verify whether scrollback returns claude's full conversation (vs. current screen only) and whether --up reveals older content — to determine if claude uses the alternate-screen buffer (which would limit terminal-scrollback history).

Not merging — PR left open per project workflow. Release build (sh release.sh) and the manual scenarios in tests/release_test.md happen in the release-testing phase.

🤖 Generated with Claude Code

[github-actions]

🔒 门禁检查结果

检查项	状态
Rust 格式化	✅ success
Rust Clippy	✅ success
Rust 测试 & 覆盖率	✅ success
前端测试 & 覆盖率	✅ success
Playwright E2E	✅ success
统一测试 (test.sh)	✅ success
安全检查	✅ success

Rust 测试覆盖率

指标	覆盖率
行覆盖率	66.0%
分支覆盖率	0.0%

模块	行覆盖率
crates.cli-box-core.src.instance	███████████████████░ 99.1%
crates.cli-box-core.src.server	█████████████████░░░ 87.7%
crates.cli-box-core.src.sandbox	███████████████████░ 98.8%
crates.cli-box-core.src.capture	████████████████████ 100.0%
crates.cli-box-core.src.process	██████████░░░░░░░░░░ 54.7%
crates.cli-box-core.src.automation	███████████░░░░░░░░░ 58.3%
crates.cli-box-core.src	███████████░░░░░░░░░ 55.3%
crates.cli-box-core.src.daemon	██████████░░░░░░░░░░ 50.7%

详细报告见 Rust 覆盖率 artifact

前端测试覆盖率

指标	覆盖率
行覆盖率	███████████████░░░░░ 75.6%
分支覆盖率	65.7%
函数覆盖率	73.4%
语句覆盖率	75.0%

文件	行覆盖率
src/tests/mocks/websocket.ts	██████████████████░░ 88.0%
src/tests/mocks/xterm.ts	████████████████████ 100.0%
src/main/daemon-bridge.ts	████████░░░░░░░░░░░░ 40.0%
src/renderer/api.ts	██████████████░░░░░░ 68.2%
src/renderer/scrollback.ts	██████████████████░░ 88.9%
src/renderer/tabState.ts	████████████████████ 100.0%
src/renderer/terminalBuffer.ts	████████████████████ 100.0%

详细报告见前端覆盖率 artifact

✅ 所有检查通过，可以合入

点击 Squash and merge 合并此PR