test(docs): verify and document the managed Devin lifecycle

[errfld]

Tracked by #6. Blocked by #2 and #3.

Why this issue exists

Support is not complete until the managed lifecycle and a real mention/reply path are proven. CI must remain hermetic while maintainers get a repeatable opt-in real-Devin runbook.

Existing seams

• Fake server: desktop/tests/e2e/fixtures/fake-acp-agent.mjs
• Live harness: desktop/tests/e2e/helpers/twoRelayHarness.ts
• Desktop harness tests: desktop/tests/e2e/harness-management.spec.ts
• Spawn/stop/sweep: desktop/src-tauri/src/managed_agents/runtime.rs, runtime/stop.rs, runtime/orphan_sweep.rs, runtime/tests.rs
• ACP lifecycle: crates/buzz-acp/src/acp.rs, pool.rs, queue.rs
• Docs: crates/buzz-acp/README.md, TESTING.md, .env.example

The generic orphan sweep is marker-based for arbitrary harness names. Add no Devin-only reaper unless a failing regression proves the generic marker/process-group path insufficient.

Work

Hermetic automation

Extend the fake ACP fixture with a Devin-shaped profile and cover:

• initialize and session creation
• auth-required plus quota/policy-style typed failures
• streamed text and shell output
• model switch success/failure
• permission request handling
• cancellation without steering
• malformed stdout/protocol exit
• graceful stop, crash, restart, and process-group cleanup
• redaction of credentials and prompt content from surfaced errors/logs

Opt-in real runbook

Document a disposable, credential-gated flow:

1. verify devin --version and devin auth status without recording auth output
2. query auth methods/models through buzz-acp
3. start one managed worker in a disposable channel/repository
4. send an owner mention asking for a unique harmless reply token
5. prove the reply was published through the bundled Buzz CLI
6. cancel an in-flight turn
7. stop/restart and verify no marked subprocess remains

State that authenticated prompts may consume quota or incur charges.

Documentation

Add “Running with Devin” to crates/buzz-acp/README.md and update TESTING.md with:

• external install/platform support
• devin auth login
• native devin acp
• optional DEVIN_MODEL
• local tool access and Buzz owner access controls
• dynamic models/account policy
• proprietary third-party status
• troubleshooting: missing CLI, logged out, policy disabled, quota, timeout, malformed protocol
• explicit non-support for TUI/--print, Cloud Devin, Outposts, and remote Devin MCP

Change .env.example only for an actual supported Buzz variable; do not invent DEVIN_API_KEY.

Acceptance criteria

• CI needs no Devin binary, account, network call, or credentials.
• Hermetic tests cover every lifecycle state above.
• Cleanup regression proves the Devin child exits with its Buzz harness.
• The opt-in runbook proves mention → turn → Buzz CLI reply and records versions without secrets.
• Docs distinguish native ACP from unsupported TUI/--print and cloud surfaces.
• Platform limits and potentially billable usage are explicit.
• Screenshots, if needed, use repository capture/posting workflows.
• just ci passes.

Suggested verification

. ./bin/activate-hermit
cargo test -p buzz-acp
cargo test --manifest-path desktop/src-tauri/Cargo.toml managed_agents::runtime
cd desktop
pnpm test
pnpm test:e2e:smoke
cd ..
just ci

For screenshot specs, call waitForAnimations(page) and build with pnpm build:e2e.

Out of scope

• Mandatory real Devin CI tests
• Bundling/relicensing Devin
• Static model snapshots
• Cloud Devin/session management
• Permission brokerage implementation (feat(acp): route permission requests to authorized Buzz owners #5)

References

• https://docs.devin.ai/cli
• https://docs.devin.ai/cli/reference/commands
• https://docs.devin.ai/cli/changelog/stable
• https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json