Claim the DevFlow mutation lease before agent mutations

[aritchie]

Fixes #251

Root cause

The issue suspected stale capture epochs, but the agent only validates epochs when the request carries one, and Sherpa never sends one. The actual 409 comes from the mutation lease that DevFlow agents enforce by default starting with 0.1.0-preview.12.26421.1 (AgentOptions.RequireMutationLease = true, confirmed in the shipped Microsoft.Maui.DevFlow.Agent.Abstractions.dll). Any v1 PUT/POST/DELETE without a claimed lease gets:

409 {"success":false,"error":"Another DevFlow session is driving this app. Take control before mutating it.","reason":"lease"}

Sherpa never claimed a lease, so every property edit failed, even on an untouched app, and refreshing the tree couldn't help. SetPropertyAsync also called EnsureSuccessStatusCode(), which dropped the error body, and the Razor handlers didn't catch the exception, so it surfaced as an unhandled Blazor error.

Changes

• DevFlowMutationLease / DevFlowMutationLeaseHandler (new): claims the lease with POST /api/v1/agent/lease (action: "claim", holder inspector, label MAUI Sherpa) before v1 mutations, and adds the same X-DevFlow-Lease/Holder/Label headers as the official AgentClient. Re-claiming renews the lease. The claim never forces a takeover. If the agent returns 404 (it predates leases), Sherpa stops claiming.
• DevFlowV1Client: every mutation (property set, UI actions, WebView input, storage, sensors, profiler, network clear) now claims the lease first. SetPropertyAsync throws a DevFlowAgentException that carries the agent's error message.
• DevFlowAgentClient: its HttpClient uses the lease handler, so profiling and the DevFlow page work against current agents too.
• DevFlowTreeTab.razor: all property editors go through SetPropertyAndRefreshAsync. It catches failures and shows a dismissible error in the Properties pane.

Testing

• New DevFlowMutationLeaseTests: the claim is sent before the mutation and the lease header matches; agents without leases keep working and aren't re-claimed; agent 409 messages reach the caller; the handler claims only for v1 mutations.
• MauiSherpa.Core.Tests: 596/596 pass. The MauiSherpa.AppInspector project builds with 0 errors.
• Not yet verified end-to-end against a live app.

Follow-up

If another DevFlow session (VS Code, Copilot) holds the lease, edits now show the agent's "Take control…" message instead of crashing. Sherpa doesn't offer a forced takeover (force: true) yet.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LMQybcsC24APNz8Vfhbbhw

[Copilot]

🔵 Needs a closer look

The lease changes span multiple mutation clients and lack live end-to-end verification.

Pull request overview

Adds DevFlow mutation-lease support for current agents and surfaces mutation errors in the Inspector.

Changes:

• Claims leases before v1 mutations with legacy-agent fallback.
• Integrates lease handling into DevFlow clients.
• Adds property error handling and lease tests.

File summaries

File	Summary
tests/MauiSherpa.Core.Tests/Services/Inspector/DevFlowMutationLeaseTests.cs	Tests lease claims and error propagation.
src/MauiSherpa.Core/Services/Inspector/DevFlowV1Client.cs	Claims leases before v1 mutations.
src/MauiSherpa.Core/Services/Inspector/DevFlowMutationLease.cs	Implements lease negotiation and HTTP handling.
src/MauiSherpa.Core/Services/DevFlowAgentClient.cs	Adds lease handling to the client.
src/MauiSherpa.AppInspector/Pages/Inspector/DevFlowTreeTab.razor	Displays property mutation errors.

Review details

• Files reviewed: 5/5 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.