Fix CompletionDock activity twitch from ACP reports

[simple-agent-manager]

Agent Preflight

• Preflight completed before code changes

Classifications

• external-api-change
• cross-component-change
• business-logic-change
• public-surface-change
• docs-sync-change
• security-sensitive-change
• ui-change
• infra-change

External References

N/A: This change is contained within SAM repo behavior and documentation; no external APIs or third-party contracts changed.

Codebase Impact Analysis

• packages/vm-agent/internal/acp/: debounce coalesces harness ACP edge activity reporting while prompt transitions remain immediate.
• packages/vm-agent/internal/config/ and packages/vm-agent/internal/server/: expose ACP_HARNESS_ACTIVITY_REPORT_DEBOUNCE with centralized default config wiring.
• apps/web/src/components/project-message-view/: CompletionDock working state uses a one-second idle stabilization delay without changing visual animation timing.
• apps/www/src/content/docs/ and .claude/: document the new VM-agent debounce configuration and activity-reporting pattern.

Documentation & Specs

Updated .claude/rules/06-vm-agent-patterns.md, .claude/skills/env-reference/SKILL.md, apps/www/src/content/docs/docs/reference/configuration.md, and apps/www/src/content/docs/docs/reference/vm-agent.md for ACP_HARNESS_ACTIVITY_REPORT_DEBOUNCE.

Constitution & Risk Check

Checked Principle XI / no hardcoded values: debounce delay is configurable via ACP_HARNESS_ACTIVITY_REPORT_DEBOUNCE and defaults are centralized in VM-agent config. The UI stabilization scope was limited to the working prop, avoiding CompletionDock visual design or animation changes.

Summary

• coalesce VM-agent harness-originated ACP activity reports with a debounced single-flight reporter and successful-report dedupe
• keep prompt start/done activity reports immediate while updating the coalescer
• add CompletionDock-specific working-state stabilization so working→idle reversals are delayed, while idle→working remains immediate
• document the new ACP_HARNESS_ACTIVITY_REPORT_DEBOUNCE setting and VM-agent callback guidance

Validation

• pnpm typecheck
• pnpm lint (existing warnings only)
• pnpm test
• pnpm build
• PATH="/workspaces/simple-agent-manager/.tmp/go-toolchain/go/bin:$PATH" go test ./... from packages/vm-agent
• PATH="/workspaces/simple-agent-manager/.tmp/go-toolchain/go/bin:$PATH" go vet ./internal/acp ./internal/config from packages/vm-agent
• PATH="/workspaces/simple-agent-manager/.tmp/go-toolchain/go/bin:$PATH" go test -race ./internal/acp ./internal/config from packages/vm-agent
• pnpm --filter @simple-agent-manager/web test -- tests/unit/components/useCompletionDockWorking.test.ts
• pnpm --filter @simple-agent-manager/web exec playwright test tests/playwright/completion-dock-audit.spec.ts --project "iPhone SE (375x667)" --project "Desktop (1280x800)" --reporter=line
• pnpm --filter @simple-agent-manager/www build
• PATH="/workspaces/simple-agent-manager/.tmp/go-toolchain/go/bin:$PATH" go test ./internal/acp from packages/vm-agent after replacing token-shaped fixtures
• pnpm quality:gitleaks:current
• pnpm quality:gitleaks:pr

Staging

• deploy run 32838455761 passed deploy and GitHub smoke-tests jobs
• live staging Codex VM task 01M0W9A19ZKHNRTED6QKGGBYW1 used fresh node 01M0W9A6P4GC57Z33PBN6SZYE7 and workspace 01M0W9KMAKSADEY31MM4BG8XN6
• fresh node reported VM-agent build a7b661f70f619d613b22bc6f32fca51b05aeb261
• during active runtime work: activity=prompting, runtimeWorkState=active, runtimeWorkCount=1, and the live UI exposed Interrupt agent
• after completion: activity=idle, runtimeWorkState=inactive, runtimeWorkCount=0, and the live UI stabilized to Sleep session
• cleanup returned staging /api/nodes and /api/workspaces to []

[codspeed-hq]

Merging this PR will not alter performance

✅ 6 untouched benchmarks

---

_{Comparing sam/fix-twitchy-completiondock-stoppause-stnnev (90841fc) with main (6bfd156)}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud