Add replay-safe fixed lease IDs to the Proxmox provider

[devinkuhn]

Goal

Add replay-safe fixed lease IDs to the direct Proxmox provider so orchestrators can call warmup --lease-id cbx_<12 hex> without weakening duplicate-allocation safeguards.

Current behavior

The Proxmox backend implements ordinary SSH leases, but does not implement IdempotentLeaseIDBackend. A fixed-ID warmup therefore fails before allocation with:

provider=proxmox does not support fixed idempotent lease IDs

The current acquire path generates a new lease ID and asks /cluster/nextid for every create. Proxmox's clone API already accepts an explicit target newid; the missing contract is durable binding and replay reconciliation in the provider.

Architecture decision

Reuse Crabbox's existing fixed-lease framework used by direct providers. Do not use the slug as identity and do not derive a VMID by truncating/hashing the lease ID into an unchecked numeric range.

For a requested fixed lease ID:

1. Persist the normalized create intent and chosen Proxmox VMID before submitting clone.
2. Submit that VMID as the clone API's newid.
3. On identical replay, inspect the persisted binding and exact VMID.
4. Adopt only when provider scope, lease labels, intent fingerprint, VMID, and native vmgenid agree.
5. Reject changed intent or conflicting/multiple resources with lease_id_conflict.
6. Preserve uncertain attempts for recovery instead of allocating another VM.
7. Retain a terminal tombstone after confirmed release/absence so the fixed operation ID is single-use.
8. Keep ordinary non-fixed Proxmox behavior unchanged.

Tests

Use strict test-first development. Cover at minimum:

• fixed-ID support is advertised;
• first fixed acquire persists intent/VMID before clone;
• identical replay returns the same lease without another clone;
• intent drift fails with lease_id_conflict;
• conflicting labels, VMID, provider scope, or vmgenid fail closed;
• ambiguous/missing post-submit state does not issue a second clone;
• release confirms exact identity and retains a terminal tombstone;
• replay after release cannot create another VM;
• ordinary non-fixed warmup remains unchanged;
• no slug-based adoption.

Documentation

Update the Proxmox provider and identifier documentation to list Proxmox among direct fixed-ID providers and describe its exact VMID/generation reconciliation contract.

Non-goals

• No OpenClaw-specific behavior or dependencies.
• No changes to Proxmox itself.
• No deterministic hash-to-VMID shortcut without durable allocation state.
• No weakening of existing cleanup ownership checks.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed September 4, 2026, 7:19 PM ET / 23:19 UTC.

Summary
Keep open: this is a concrete, distinct provider capability that remains absent from reviewed main and the supplied release, v0.48.1. The current rejection is intentional capability gating, not a regression.

Reproducibility: yes. from source: with a valid Proxmox configuration, warmup with a canonical --lease-id reaches the unsupported-capability guard before allocation. This was not executed and demonstrates a missing feature rather than broken existing behavior.

Maintainer decision needed

Question	Recommendation
Should initial fixed-ID Proxmox support retain an interrupted clone as a blocked pending operation whenever exact VMID and generation ownership cannot be established?	Approve fail-closed initial support: Allow provider-local fixed IDs while retaining ambiguous attempts without replacement allocation or adoption until exact ownership can be proven.

Why: The current clone path establishes labels and observes generation after submission; deciding whether incomplete attempts require manual recovery defines the supported safety and recovery contract.

Next step
Obtain approval for the pending-clone recovery contract before implementation; this new ownership-sensitive lifecycle is not a safe strict bug-fix dispatch.

Security
Needs attention: The proposed adoption and release contract is security-sensitive; no existing unauthorized operation was demonstrated.

Review details

Best possible solution:

Extend the shared fixed-lease mechanism through the Proxmox adapter, with durable pre-clone VMID binding, a downgrade-safe claim format, exact-generation release checks, permanent tombstones, and unchanged ordinary acquisition.

Do we have a high-confidence way to reproduce the issue?

Yes, from source: with a valid Proxmox configuration, warmup with a canonical --lease-id reaches the unsupported-capability guard before allocation. This was not executed and demonstrates a missing feature rather than broken existing behavior.

Is this the best way to solve the issue?

Yes, reusing the existing fixed-lease framework is the narrowest maintainable direction; enabling the capability alone would be unsafe because Proxmox still needs durable attempt reconciliation and terminal release handling.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• An interrupted clone can exist before lease labels and its native generation are durably bound; automatic recovery must not mistake a reused VMID for the original allocation.
• Fixed claims need downgrade-safe routing and permanent tombstone retention across release and automatic cleanup, whose existing Proxmox paths are designed for removable ordinary claims.

Codex review notes: model internal, reasoning high; reviewed against bd672e05c90a.

Label changes

Label changes:

• add P2: This is a bounded provider capability improvement for replay-safe orchestration, with ordinary Proxmox leases still supported.
• add impact:security: The requested contract explicitly governs authorization to adopt and destroy an exact VM incarnation.
• add impact:other: The missing capability prevents orchestrators requiring fixed operation IDs from using the direct Proxmox provider.
• add issue-rating: 🦞 diamond lobster: Current issue advisory state selects this label.
• add clawsweeper:source-repro: Current issue advisory state selects this label.
• add clawsweeper:no-new-fix-pr: Current issue advisory state selects this label.
• add clawsweeper:needs-product-decision: Current issue advisory state selects this label.
• add clawsweeper:needs-security-review: Current issue advisory state selects this label.

Label justifications:

• P2: This is a bounded provider capability improvement for replay-safe orchestration, with ordinary Proxmox leases still supported.
• impact:other: The missing capability prevents orchestrators requiring fixed operation IDs from using the direct Proxmox provider.
• impact:security: The requested contract explicitly governs authorization to adopt and destroy an exact VM incarnation.

Evidence reviewed

Security concerns:

• [medium] Define ownership recovery for incompletely bound clones — internal/cli/proxmox.go:1028
  Clone submission precedes lease-label configuration and generation binding. The new fixed-ID path must retain uncertainty rather than authorize adoption or deletion using the VMID alone, including when that VMID has been reused.
  Confidence: 0.96

What I checked:

• Repository identity and applicable policy: The origin identifies openclaw/crabbox, and checked-out main matches the supplied review SHA. The full root AGENTS.md was read; no additional AGENTS.md files were found under internal or docs. Its provider-neutral core and provider-owned reconciliation guidance applies. (AGENTS.md:13, bd672e05c90a)
• Fixed-ID rejection occurs before acquisition: warmup validates the requested ID and requires IdempotentLeaseIDBackend before invoking acquisition. Proxmox's backend and its embedded DirectSSHBackend do not implement SupportsRequestedLeaseID, so the reported unsupported-provider error follows directly from current source. (internal/cli/run.go:87, bd672e05c90a)
• Ordinary Proxmox acquisition does not consume a fixed ID: Acquire forwards keep and requested slug to the ordinary retry path; acquireOnce generates a fresh lease ID. Provider.Spec declares a direct SSH provider with no coordinator, so coordinator fixed-ID support does not supply the missing Proxmox capability. (internal/providers/proxmox/backend.go:61, bd672e05c90a)
• Clone submission and ownership-binding boundary: CreateServer obtains a fresh nextID and passes it as clone newid. Lease labels are configured only after clone completion, while vmgenid is subsequently read into Server.ImmutableID. Fixed acquisition therefore needs a durable pre-submit attempt and an explicit policy for interruption before complete identity binding. (internal/cli/proxmox.go:1007, bd672e05c90a)
• Reusable fixed-lease framework already exists: AcquireFixedLease persists normalized intent before its provider acquisition callback and rejects mismatched or terminal claims. FixedLeaseKind supplies durable tombstone finalization, and local-container demonstrates persisting an attempt before creation and rejecting unresolved retries. These are implementation foundations, not existing Proxmox support. (internal/cli/fixed_lease.go:52, bd672e05c90a)
• Existing ownership contract must survive the extension: Automatic cleanup requires exact claim scope, VMID, lease metadata, and native generation, with live rechecks before destructive operations. Tests reject recreated VMIDs, changed generations, mismatched scopes, and duplicate bindings without stop or delete calls. Successful ordinary cleanup currently removes its claim rather than retaining a fixed-operation tombstone. (internal/providers/proxmox/cleanup_test.go:141, bd672e05c90a)

Likely related people:

• Peter Steinberger: Raw commit 728fe0f adds internal/providers/proxmox/cleanup.go:56 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: 728fe0fcaa7a; files: internal/providers/proxmox/cleanup.go)
• Vincent Koc: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.