feat(agents): add the shared Sandbox lifecycle contract

[tee8z]

The desktop provider and the in-cluster buzz-sandbox-reaper must agree on the state of each Agent Sandbox session.
This PR adds a library target, buzz_backend_kubernetes::lifecycle, with the lifecycle annotation keys and a pure classifier.
classify() reads one Observation of the Sandbox, its Pod, and the apiserver clock, and returns one State.
The harness in buzz-acp now records its saved checkpoint key where the reaper can read it.

stateDiagram-v2
    state "Ignored (unmarked)" as Unmarked
    state "Ignored (foreign-owner)" as ForeignOwner
    state "Ignored (foreign-pod)" as ForeignPod
    state "Ignored (inconsistent)" as Inconsistent
    state "Ignored (not-running)" as NotRunning
    state cMarker <<choice>>
    state cOwner <<choice>>
    state cDeleting <<choice>>
    state cLifecycle <<choice>>
    state cEnding <<choice>>
    state cMode <<choice>>
    state cPod <<choice>>
    state cBinding <<choice>>
    state cContainer <<choice>>
    [*] --> cMarker
    cMarker --> Unmarked : no management label, or binding version is not 2
    cMarker --> cOwner : marked
    cOwner --> ForeignOwner : owner annotation differs
    cOwner --> cDeleting : owner matches
    cDeleting --> Draining : Sandbox deleting
    cDeleting --> cLifecycle : not deleting
    cLifecycle --> Ended : ended and Suspended
    cLifecycle --> cEnding : ending
    cLifecycle --> Inconsistent : ended but not Suspended, or unknown value
    cLifecycle --> cMode : no lifecycle annotation
    cEnding --> Draining : owned Pod present
    cEnding --> ForeignPod : foreign Pod present
    cEnding --> Ending : no Pod
    cMode --> NotRunning : operatingMode is not Running
    cMode --> cPod : Running
    cPod --> ForeignPod : Pod not owned by the Sandbox
    cPod --> Draining : owned Pod deleting
    cPod --> cBinding : no Pod, or owned live Pod
    cBinding --> Binding : no initial-pod-uid
    cBinding --> Lost : bound, no Pod
    cBinding --> Replaced : Pod UID differs from initial-pod-uid
    cBinding --> cContainer : Pod UID matches
    cContainer --> BindingIncomplete : never started
    cContainer --> Active : running
    cContainer --> Completed : terminated

Loading

Constant	Value	Sets
BIND_TIMEOUT_SECS	1200 s	Binding { abandoned }, BindingIncomplete { expired }
LOST_GRACE_SECS	60 s	Lost { confirmed }
ENDED_RETENTION_SECS	30 days	Ended { expired }

MISSING_CHECKPOINT_HOLD_SECS (24 h) is defined for the reaper; classify() does not use it.
An Ending state without an ended-reason annotation uses stopped.

Checkpoint receipt:

• After a successful save, buzz-acp writes {"version":1,"checkpoint":"<key>"} to /dev/termination-log.
• The harness only opens an existing file. A local run has no file, so nothing is written.
• receipt_key() accepts only version 1 and a key directly under the session prefix <developer prefix><generation>/.

naming.rs now re-exports MANAGED_BY, LABEL_MANAGED_BY, LABEL_BINDING_VERSION, and ANNOTATION_PUBKEY_FULL from the library.

Stack

Position 7 of 20 in the DEV-2884 Buzz stack. Base: #1. Next: #14.

Validation

• cargo fmt --check -p buzz-acp -p buzz-backend-kubernetes: pass.
• cargo clippy -p buzz-backend-kubernetes --all-targets -- -D warnings: pass.
• cargo clippy -p buzz-acp --all-targets -- -D warnings: pass.
• cargo test -p buzz-backend-kubernetes: lib 12 passed; bin 167 passed, 1 ignored; wire_fixtures 5 passed.
• cargo test -p buzz-acp checkpoint: 5 passed.
• cargo test -p buzz-acp: 1069 passed, 3 ignored; other test binaries 4, 9, 9, 1 passed. Run on the stack head; crates/buzz-acp does not change after this PR.

Limits

• The ignored test live_controller_reuses_scopes_and_refuses_lost_workspaces needs the kind-remote-agent-check cluster. It was not run.
• sandbox.rs still keeps its own copies of the annotation keys and helpers. The next PR in the stack moves it onto the library.
• Buzz AGENTS.md requires a human to test the change before it leaves draft.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}