feat(backend): Phase 3 agent scheduling - item claim/heartbeat/release/done

[getappz]

Summary

• New item_claims table + claim.rs module in agentflare-backend - a thin wrapper over agentflare-db-kit's generic ClaimLedger (no bespoke atomic-upsert SQL duplicated here; that logic is already race-fixed and unit-tested in db-kit).
• item::claim/item::claim_done compose the lease with item state: claiming an unclaimed item sets the assignee and moves state into the project's "started" group (started_at set via the existing update_state); marking done moves it into "completed" and frees the claim for reclaiming by anyone. A live claim held by another owner returns Held and leaves the item untouched.
• Four new MCP tools added to the existing single #[tool_router] block: backend_item_claim, backend_item_heartbeat, backend_item_release, backend_item_done.
• TTL defaults to 4h, configurable via AGENTFLARE_BACKEND_CLAIM_TTL_SECS - deliberately separate from src/claims.rs's AGENTFLARE_CLAIM_TTL_SECS (30 min default for GitHub-issue claims) since work items claimed here are plausibly longer-running.

Test plan

• cargo test --workspace - all green (333 in the main binary, 55 in agentflare-backend incl. 7 new claim tests, 9 in agentflare-db-kit unchanged)
• cargo clippy --workspace --all-targets -- -D warnings -A unsafe_code -A clippy::pedantic - clean (CI's actual gate)
• cargo fmt --check - clean
• cargo deny check - advisories/bans/licenses/sources all ok
• Confirmed exactly one #[tool_router]-tagged impl block (grep-verified)
• New tests cover: fresh claim acquires + sets assignee + moves to started; claiming an already-held item returns Held and leaves the item unchanged; a stale claim is stealable by a different owner; claim_done moves to completed and is re-claimable; heartbeat/release/done are owner-scoped

Summary by CodeRabbit

• New Features
  • Added item-claim leasing with ownership, expiration (TTL), heartbeat liveness tracking, and explicit release/done flows.
  • Introduced backend claiming endpoints that atomically transition items into “started” on acquire and “completed” on done, updating assignee and timestamps.
  • Added new MCP tools to acquire, heartbeat, release, and complete item claims.
• Bug Fixes
  • Prevents conflicting owners from claiming items already held.
  • Expired or stale claims can be safely reclaimed only by the new owner.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: d4544246-0da4-468c-bec2-7f2b20782ae2

📥 Commits

Reviewing files that changed from the base of the PR and between f2bc054 and e90965e.

📒 Files selected for processing (1)

• crates/agentflare-backend/src/item.rs

🚧 Files skipped from review as they are similar to previous changes (1)

• crates/agentflare-backend/src/item.rs

---

📝 Walkthrough

Walkthrough

The backend adds persistent item claims with acquisition, heartbeat, release, and completion operations. Successful claims update item ownership and state, while MCP tools expose the claim lifecycle with configurable TTL handling.

Changes

Item claiming

Layer / File(s)	Summary
Claim persistence and state lookup crates/agentflare-backend/Cargo.toml, crates/agentflare-backend/src/{schema.sql,claim.rs,state.rs,lib.rs}	Adds the item_claims table, claim ledger wrapper APIs, public module wiring, and first_in_group state lookup with tests.
Item claim lifecycle crates/agentflare-backend/src/item.rs	Adds item claim and completion operations, started/completed state transitions, ownership checks, expiry handling, and lifecycle tests.
MCP claim tools src/mcp_server.rs	Adds configurable claim TTL handling and MCP handlers for claim, heartbeat, release, and completion operations.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant MCPClient
  participant AgentflareMcp
  participant Backend
  participant ItemClaims
  participant ItemState
  MCPClient->>AgentflareMcp: Claim item_id
  AgentflareMcp->>Backend: item::claim(item_id, owner, now, ttl)
  Backend->>ItemClaims: Acquire claim
  ItemClaims-->>Backend: Acquisition result
  Backend->>ItemState: Update owner and started state
  Backend-->>AgentflareMcp: Claim result
  AgentflareMcp-->>MCPClient: Status JSON
  MCPClient->>AgentflareMcp: Complete item_id
  AgentflareMcp->>Backend: item::claim_done(item_id, owner, now)
  Backend->>ItemClaims: Complete claim
  Backend->>ItemState: Update completed state
  Backend-->>AgentflareMcp: Completion result
  AgentflareMcp-->>MCPClient: Done JSON

Loading

Possibly related PRs

• getappz/agentflare#141: Adds a similar SQLite claims ledger API and MCP claim tooling flow.

Suggested labels: enhancement, rust

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly matches the main change: backend item claim lifecycle support.
Description check	✅ Passed	Summary and test plan are complete and well matched to the template; Notes for reviewers are the only missing section.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/agentflare-backend-phase3

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@crates/agentflare-backend/src/item.rs`:
- Around line 415-427: Make the claim lifecycle operations atomic: in
crates/agentflare-backend/src/item.rs lines 415-427, wrap acquisition, the
started-state transition, and assignee update in one transaction; in lines
435-440, wrap the done transition and completed-state update in the same
transaction. Update the surrounding item lifecycle methods without changing
their existing success or failure behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 44ec386b-196a-434d-bf73-70dfdb2f7842

📥 Commits

Reviewing files that changed from the base of the PR and between 731ae3e and f2bc054.

⛔ Files ignored due to path filters (1)

• Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (7)

• crates/agentflare-backend/Cargo.toml
• crates/agentflare-backend/src/claim.rs
• crates/agentflare-backend/src/item.rs
• crates/agentflare-backend/src/lib.rs
• crates/agentflare-backend/src/schema.sql
• crates/agentflare-backend/src/state.rs
• src/mcp_server.rs