feat(assignments): add recoverable claim leases (#86)

* feat(assignments): add recoverable claim leases

* docs(assignments): clarify claim fence errors

Author: chicoxyzzy

AGENTS.md

@@ -18,6 +18,9 @@ alpha and not stable.
 - Keep tool registration/application wiring in `internal/app`.
 - Assignment records are coordination state; execution and launch authority stay
   outside core.
+- Portable worker claims use server-issued fencing ids. Never add claim expiry
+  without fencing prepare/progress/completion writes, and never infer that an
+  expired reservation means host runtime execution is dead.
 - Skill metadata never grants tools, writes, network, or approval bypass.
 
 ## Skills

README.md

@@ -75,6 +75,13 @@ policy, credential handling, or logged-in session boundaries. Secrets, cookies,
 provider credentials, and external-agent private memory are outside Cairnline's
 core model.
 
+MCP assignment claims carry a server-issued `claim.id`. It is a concurrency
+fence, not a bearer credential or proof of identity. Hosts must still decide who
+may call mutation tools. The pre-start reservation expires after the TTL
+advertised by `coordination.capabilities`; expiry only makes an explicit
+`assignments.recover_claim` possible. Cairnline never treats a running agent as
+dead, cancels host execution, or requeues running work automatically.
+
 Cairnline assignment metadata is not authorization. Agent hosts and
 orchestrators must enforce their own policy boundaries even when an assignment
 asks for a particular execution mode, desired agent kind, or skill id.
@@ -102,6 +109,9 @@ Implemented now:
   collaboration artifacts
 - SQLite store for durable projects, project roles, work items, assignments,
   skill metadata, assistant proposal records, and collaboration artifacts
+- expiring, renewable MCP assignment reservations with server-issued fencing
+  ids; expired pre-start claims can be explicitly recovered without allowing a
+  stale worker to prepare, start, or complete a later claim generation
 - project skill discovery from interoperable `.agents/skills`,
   Cairnline-native `.cairnline/skills`, Claude-compatible `.claude/skills`,
   Gemini-compatible `.gemini/skills`, compatibility `.hecate/skills`, and
@@ -131,6 +141,8 @@ discovery; both were checked on July 4, 2026:
   snapshots cover projects, skills, roles, work,
   assignments, artifacts, evidence, reviews, handoffs, memory entries,
   memory candidates, and assistant proposal records
+  (snapshot v2 preserves claim fences and still accepts v1 imports as
+  host-authoritative unleased historical claims)
 - stdio MCP server with JSON-RPC framing
 - MCP protocol structs carry the spec fields a richer tool surface needs: tool
   `outputSchema`, `_meta` passthrough on tools, resources, resource content, and
@@ -191,6 +203,8 @@ discovery; both were checked on July 4, 2026:
   - `assignments.create`
   - `assignments.update`
   - `assignments.claim`
+  - `assignments.renew_claim`
+  - `assignments.recover_claim`
   - `assignments.prepare`
   - `assignments.release`
   - `assignments.update_status`
@@ -231,11 +245,12 @@ discovery; both were checked on July 4, 2026:
 - read-only work-item closeout readiness summaries derived from assignment,
   evidence, review, and handoff metadata
 - read-only project operations briefs for attention routing across active
-  assignments, blocked closeout, review follow-up, memory candidates, and open
-  work
+  assignments, expired pre-start claims, blocked closeout, review follow-up,
+  memory candidates, and open work
 - read-only project activity projections grouped by active, blocked, completed,
   and recent assignment state; queued assignments are attention items until
-  claimed, while claimed/running/review assignments are active
+  claimed, unexpired claimed/running/review assignments are active, and expired
+  pre-start claims are blocked recovery items
 - read-only project setup-readiness and health summaries for onboarding,
   context/skill gaps, and bounded operator attention
 - deterministic assistant proposal/apply tools with durable proposal records,

cairnline.go

@@ -8,6 +8,7 @@ package cairnline
 
 import (
 	"context"
+	"time"
 
 	"github.com/hecatehq/cairnline/internal/app"
 	"github.com/hecatehq/cairnline/internal/core"
@@ -24,6 +25,7 @@ var (
 
 type Store = core.Store
 type Service = core.Service
+type ServiceOption = core.ServiceOption
 type MemoryStore = core.MemoryStore
 type SQLiteStore = sqlitestore.Store
 
@@ -60,6 +62,7 @@ type ReviewFollowUpReadiness = core.ReviewFollowUpReadiness
 type DesiredAgent = core.DesiredAgent
 type ExecutionRef = core.ExecutionRef
 type Assignment = core.Assignment
+type AssignmentClaimLease = core.AssignmentClaimLease
 type AssignmentCoordination = core.AssignmentCoordination
 type QueuedAssignmentUpdate = core.QueuedAssignmentUpdate
 type AssignmentPreparation = core.AssignmentPreparation
@@ -84,7 +87,8 @@ type MemoryCandidatePromotion = core.MemoryCandidatePromotion
 type Snapshot = core.Snapshot
 
 const (
-	SnapshotVersion = core.SnapshotVersion
+	SnapshotVersion                = core.SnapshotVersion
+	DefaultAssignmentClaimLeaseTTL = core.DefaultAssignmentClaimLeaseTTL
 
 	WorkStatusReady = core.WorkStatusReady
 	WorkStatusDone  = core.WorkStatusDone
@@ -207,6 +211,7 @@ const (
 	ProjectOperationKindProjectSetup    = core.ProjectOperationKindProjectSetup
 	ProjectOperationKindSkill           = core.ProjectOperationKindSkill
 	ProjectOperationKindWorkItem        = core.ProjectOperationKindWorkItem
+	ProjectOperationActionRecoverClaim  = core.ProjectOperationActionRecoverClaim
 
 	ProjectOperationSeverityBlocked = core.ProjectOperationSeverityBlocked
 	ProjectOperationSeverityAction  = core.ProjectOperationSeverityAction
@@ -222,8 +227,15 @@ const (
 	LaunchPacketKindAssignment = core.LaunchPacketKindAssignment
 )
 
-func NewService(store Store) *Service {
-	return core.NewService(store)
+func NewService(store Store, options ...ServiceOption) *Service {
+	return core.NewService(store, options...)
+}
+
+// WithAssignmentClaimLeaseTTL configures the pre-start lease used by portable
+// worker claims created through ClaimAssignmentWithLease and MCP. Positive
+// values are rounded up to whole seconds with a one-second minimum.
+func WithAssignmentClaimLeaseTTL(ttl time.Duration) ServiceOption {
+	return core.WithAssignmentClaimLeaseTTL(ttl)
 }
 
 func NewMemoryStore() *MemoryStore {

cairnline_test.go

@@ -5,6 +5,7 @@ import (
 	"errors"
 	"path/filepath"
 	"testing"
+	"time"
 
 	"github.com/hecatehq/cairnline"
 )
@@ -87,6 +88,45 @@ func TestPublicAPIEmbedsCoordinationCore(t *testing.T) {
 	}
 }
 
+func TestPublicAPIExposesFencedAssignmentClaims(t *testing.T) {
+	if cairnline.ProjectOperationActionRecoverClaim != "recover_assignment_claim" {
+		t.Fatalf("ProjectOperationActionRecoverClaim = %q, want stable public action", cairnline.ProjectOperationActionRecoverClaim)
+	}
+	ctx := context.Background()
+	service := cairnline.NewService(cairnline.NewMemoryStore(), cairnline.WithAssignmentClaimLeaseTTL(90*time.Second))
+	project, err := service.CreateProject(ctx, cairnline.Project{Name: "Portable claim"})
+	if err != nil {
+		t.Fatalf("CreateProject() error = %v", err)
+	}
+	role, err := service.CreateRole(ctx, cairnline.Role{ProjectID: project.ID, Name: "Worker"})
+	if err != nil {
+		t.Fatalf("CreateRole() error = %v", err)
+	}
+	work, err := service.CreateWorkItem(ctx, cairnline.WorkItem{ProjectID: project.ID, Title: "Fence worker"})
+	if err != nil {
+		t.Fatalf("CreateWorkItem() error = %v", err)
+	}
+	assignment, err := service.CreateAssignment(ctx, cairnline.Assignment{ProjectID: project.ID, WorkItemID: work.ID, RoleID: role.ID})
+	if err != nil {
+		t.Fatalf("CreateAssignment() error = %v", err)
+	}
+	claimed, err := service.ClaimAssignmentWithLease(ctx, project.ID, assignment.ID, "portable-worker")
+	if err != nil {
+		t.Fatalf("ClaimAssignmentWithLease() error = %v", err)
+	}
+	var claim *cairnline.AssignmentClaimLease = claimed.Claim
+	if claim == nil || claim.ID == "" || claim.ExpiresAt.Sub(claim.AcquiredAt) != 90*time.Second {
+		t.Fatalf("claim = %+v, want public 90-second fence", claim)
+	}
+	running, err := service.UpdateAssignmentStatusWithClaim(ctx, project.ID, assignment.ID, cairnline.AssignmentRunning, cairnline.ExecutionRef{}, claim.ID)
+	if err != nil {
+		t.Fatalf("UpdateAssignmentStatusWithClaim() error = %v", err)
+	}
+	if running.Claim == nil || running.Claim.ID != claim.ID || !running.Claim.ExpiresAt.IsZero() {
+		t.Fatalf("running claim = %+v, want retained public fence", running.Claim)
+	}
+}
+
 func TestPublicAPIOpensSQLiteStore(t *testing.T) {
 	ctx := context.Background()
 	service, store, err := cairnline.NewSQLiteService(ctx, filepath.Join(t.TempDir(), "cairnline.db"))

cmd/cairnline/main_test.go

@@ -126,11 +126,32 @@ func TestCommand_StandaloneMCPPullSmoke(t *testing.T) {
 	if !strings.Contains(nextText, assignmentID) {
 		t.Fatalf("assignments.next text = %q, want assignment %s", nextText, assignmentID)
 	}
-	claimText := request.toolText(7, "assignments.claim", map[string]any{
-		"project_id":    projectID,
-		"assignment_id": assignmentID,
-		"claimed_by":    "standalone-smoke-agent",
+	claimResponse := request.raw(7, "tools/call", map[string]any{
+		"name": "assignments.claim",
+		"arguments": map[string]any{
+			"project_id":    projectID,
+			"assignment_id": assignmentID,
+			"claimed_by":    "standalone-smoke-agent",
+		},
 	})
+	var claimResult struct {
+		Content []struct {
+			Text string `json:"text"`
+		} `json:"content"`
+		StructuredContent struct {
+			Claim *struct {
+				ID string `json:"id"`
+			} `json:"claim"`
+		} `json:"structuredContent"`
+	}
+	if err := json.Unmarshal(claimResponse.Result, &claimResult); err != nil {
+		t.Fatalf("claim response did not unmarshal: %v\n%s", err, string(claimResponse.Result))
+	}
+	if len(claimResult.Content) == 0 || claimResult.StructuredContent.Claim == nil {
+		t.Fatalf("claim response missing content or lease: %s", string(claimResponse.Result))
+	}
+	claimText := claimResult.Content[0].Text
+	claimID := claimResult.StructuredContent.Claim.ID
 	if !strings.Contains(claimText, "Claimed assignment "+assignmentID+" by standalone-smoke-agent") {
 		t.Fatalf("claim text = %q, want claimed assignment", claimText)
 	}
@@ -157,6 +178,7 @@ func TestCommand_StandaloneMCPPullSmoke(t *testing.T) {
 	completeText := request.toolText(10, "assignments.complete", map[string]any{
 		"project_id":    projectID,
 		"assignment_id": assignmentID,
+		"claim_id":      claimID,
 		"status":        "completed",
 		"execution_ref": map[string]any{"run_id": "standalone-smoke-run"},
 	})

docs/agent-host-integration.md

@@ -82,10 +82,73 @@ updated, err := service.UpdateQueuedAssignment(ctx, projectID, assignment.ID,
 The update is compare-and-set: it preserves lifecycle/execution fields and
 returns `ErrConflict` if another writer changed or claimed the assignment.
 This prevents a stale editor from releasing a claim that may already have
-started execution. After a claim, use `Service.PrepareAssignment` to attach a
-host execution reference or context snapshot while verifying the expected
-claim owner. Snapshot import remains an administrative/offline workflow and is
-not exposed as a live whole-assignment mutation.
+started execution. Snapshot import remains an administrative/offline workflow
+and is not exposed as a live whole-assignment mutation.
+
+### Portable worker claims and host authority
+
+Portable MCP workers use a fenced pre-start claim rather than relying on the
+caller-chosen `claimed_by` label:
+
+```text
+queued ── claim ──> claimed (lease active) ── start ──> running (fence retained)
+                       │
+                       └── expiry + explicit recover ──> queued
+```
+
+1. `Service.ClaimAssignmentWithLease` returns an assignment whose `claim`
+   contains a server-generated `id`, `acquired_at`, and `expires_at`.
+2. While status is `claimed`, call `Service.RenewAssignmentClaim` before the
+   expiry when provisioning or context preparation may take longer than the
+   configured TTL. `WithAssignmentClaimLeaseTTL` changes the default five
+   minutes for an embedding server; `coordination.capabilities` reports the
+   effective value. Positive custom values are rounded up to whole seconds
+   with a one-second minimum.
+3. Pass the exact claim id to `PrepareAssignmentWithClaim`,
+   `ReleaseAssignmentWithClaim`, `UpdateAssignmentStatusWithClaim`, and
+   `CompleteAssignmentWithClaim`. Missing ids are invalid; expired or
+   superseded ids conflict.
+4. When work advances out of `claimed`, Cairnline retires the reservation
+   expiry but retains its id as a fencing generation for later worker writes.
+
+Claim ids are concurrency values, not authentication credentials. They may be
+stored in portable snapshots and returned in assignment reads. Hosts still
+decide which principals may invoke these methods or their MCP tools. For
+content-only MCP clients, `assignments.get` and `assignments.list` include
+`claim_id` plus `claim_expires_at` while the reservation is active, or
+`claim_fence` after work starts.
+
+If a pre-start claim expires, it stays `claimed` until an authorized host or
+operator calls `RecoverAssignmentClaim` with the exact expired id. Recovery
+requeues it and clears prepared execution/context references. This operation is
+explicit so the host can reconcile any resources it created during preparation.
+`projects.operations_brief` and `projects.health` expose the stable
+`recover_assignment_claim` action hint for this state.
+It is never valid for `running`, `awaiting_approval`, or `awaiting_review` work:
+Cairnline cannot determine that host execution is dead and never cancels or
+requeues it automatically.
+
+The original `ClaimAssignment`, `PrepareAssignment`, `ReleaseAssignment`,
+`UpdateAssignmentStatus`, and `CompleteAssignment` methods remain
+embedding-host authority surfaces for trusted reconciliation and existing
+Hecate integration. They bypass worker fencing by design and must not be
+exposed directly as agent tools. Embedders with custom `Store`
+implementations must implement the new claim-lease methods before upgrading.
+
+Breaking (alpha): the portable worker claim contract is now fenced.
+`assignments.prepare` and `assignments.release` take `claim_id` instead of
+`claimed_by`; `assignments.update_status` and `assignments.complete` also
+require the current `claim_id`. `assignments.claim` returns that id in both its
+text and structured result. The public `Store` interface adds the seven leased
+claim/renew/recover and fenced mutation methods, so custom stores must implement
+them. Snapshot version 2 persists claim generations; version 1 imports remain
+supported only as unleased host-authoritative history.
+
+SQLite migration and v1 snapshot import preserve existing claimed rows as
+unleased host-authoritative state; they do not invent an expiry or silently
+make old work stealable. Before handing one of those rows to an MCP worker, a
+trusted embedding host must reconcile/release it and let the worker claim it
+again under the leased contract.
 
 Handoff editors follow the same rule. Use `Service.PatchHandoff`,
 `Service.UpdateHandoffStatus`, or `Service.DeleteHandoff` with the exact
@@ -131,6 +194,7 @@ Hosts that want agent-neutral interoperability should start here:
 coordination.capabilities
 assignments.next
 assignments.claim
+assignments.renew_claim (only while still claimed and nearing expiry)
 assignments.context
 assignments.launch_packet
 evidence.record
@@ -140,15 +204,22 @@ assignments.complete
 1. Call `coordination.capabilities` once during setup or health checks to learn
    the server contract and boundaries.
 2. Poll `assignments.next` with the host's available kind and skill ids.
-3. Claim one assignment with `assignments.claim`.
+3. Claim one assignment with `assignments.claim` and retain the returned
+   `structuredContent.claim.id` fencing value.
 4. Read `assignments.context` and/or `assignments.launch_packet`. Both include
    the project's enabled durable memory entries.
-5. Build the host-native prompt/run packet from the structured metadata.
-6. Record evidence as the run produces useful proof.
-7. Complete, fail, or cancel the assignment explicitly.
-
-If the host crashes after claim, it should either resume by `execution_ref` or
-release the claim when it knows work will not continue.
+5. Renew with `assignments.renew_claim` if the assignment remains `claimed` as
+   expiry approaches. Pass the claim id to prepare, progress, and completion
+   mutations.
+6. Build the host-native prompt/run packet from the structured metadata.
+7. Record evidence as the run produces useful proof.
+8. Complete, fail, or cancel the assignment explicitly.
+
+If the host crashes before work starts, another authorized host may explicitly
+call `assignments.recover_claim` once the reservation expires, then claim the
+queued assignment again. If it crashes after work starts, the executing host
+must reconcile or resume through its `execution_ref`; claim expiry never makes
+runtime work stealable.
 
 ## Execution Ref And Approval Signal
 
@@ -410,11 +481,14 @@ Before exposing Cairnline tools to an agent, a host should decide:
 
 - Which mutating tools the agent may call.
 - Whether assignments can be claimed automatically or require operator review.
+- Which component renews pre-start claims, how it retains the non-secret claim
+  id, and how it stops stale workers after a conflict.
 - Whether evidence locators are only stored, rendered as text, or opened as
   links after scheme validation.
 - Whether local roots are readable by the host, and under what path boundary.
 - Whether skill metadata may trigger host-native instruction loading.
-- How to recover or release claimed assignments after crashes.
+- How to reconcile prepared host resources before recovering an expired claim,
+  and how to handle running work separately through host supervision.
 - How to show operator confirmation for memory promotion and destructive
   project changes.
 - Whether to render `ui://` app views, and if so, only inside a sandboxed
@@ -428,6 +502,8 @@ A minimal useful integration does not need orchestration. It only needs:
 - `projects.list`
 - `assignments.next`
 - `assignments.claim`
+- `assignments.renew_claim` when pre-start work approaches expiry
+- `assignments.recover_claim` for explicit expired-claim recovery
 - `assignments.context`
 - `assignments.launch_packet`
 - `evidence.record`