fix(assignments): make transitions atomic

Author: chicoxyzzy

README.md

@@ -191,6 +191,7 @@ discovery; both were checked on July 4, 2026:
   - `assignments.create`
   - `assignments.update`
   - `assignments.claim`
+  - `assignments.prepare`
   - `assignments.release`
   - `assignments.update_status`
   - `assignments.context`

cairnline.go

@@ -60,6 +60,9 @@ type ReviewFollowUpReadiness = core.ReviewFollowUpReadiness
 type DesiredAgent = core.DesiredAgent
 type ExecutionRef = core.ExecutionRef
 type Assignment = core.Assignment
+type AssignmentCoordination = core.AssignmentCoordination
+type QueuedAssignmentUpdate = core.QueuedAssignmentUpdate
+type AssignmentPreparation = core.AssignmentPreparation
 type AssignmentCompatibilityFilter = core.AssignmentCompatibilityFilter
 type AssignmentContext = core.AssignmentContext
 type AssignmentLaunchPacket = core.AssignmentLaunchPacket

docs/agent-host-integration.md

@@ -63,6 +63,38 @@ manual
 The mode is a request, not authorization. A host may downgrade, ignore, or
 reject a mode if its policy does not allow it.
 
+Embedding hosts that let operators change a queued assignment's role, root,
+execution mode, or desired-agent metadata should use
+`Service.UpdateQueuedAssignment` with the exact coordination snapshot and
+`updated_at` value that were read:
+
+```go
+replacement := assignment.Coordination()
+replacement.RoleID = newRoleID
+updated, err := service.UpdateQueuedAssignment(ctx, projectID, assignment.ID,
+	cairnline.QueuedAssignmentUpdate{
+		Expected:          assignment.Coordination(),
+		ExpectedUpdatedAt: assignment.UpdatedAt,
+		Replacement:       replacement,
+	})
+```
+
+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.
+
+Progress and completion transitions are also atomic, and terminal completion is
+first-writer-wins. Once an assignment is completed, failed, or cancelled, later
+progress or terminal writes return `ErrConflict`. Completion preserves an
+existing `started_at`. A direct queued completion or failure records the
+transition as both start and finish for compatibility; cancelling queued work
+records only `completed_at`, so portable readers do not report that unstarted
+work began.
+
 ## Recommended MCP Pull Flow
 
 Hosts that want agent-neutral interoperability should start here:

docs/mcp-quickstart.md

@@ -109,6 +109,21 @@ Replace `WORK_ITEM_ID` with the generated work item id.
 
 Cairnline does not perform the launch for any of these modes.
 
+#### Optional: edit the queued assignment safely
+
+Read the assignment with `assignments.get`, then pass its exact coordination
+fields and `updated_at` back as the expected snapshot. Only the replacement
+fields may differ:
+
+```json
+{"jsonrpc":"2.0","id":"4-edit","method":"tools/call","params":{"name":"assignments.update","arguments":{"project_id":"PROJECT_ID","assignment_id":"ASSIGNMENT_ID","expected":{"work_item_id":"WORK_ITEM_ID","role_id":"ROLE_ID","root_id":"","execution_mode":"mcp_pull","desired_agent":{"kind":"any","skill_ids":["review"]}},"expected_updated_at":"ASSIGNMENT_UPDATED_AT","replacement":{"work_item_id":"WORK_ITEM_ID","role_id":"NEW_ROLE_ID","root_id":"","execution_mode":"manual","desired_agent":{"kind":"human","skill_ids":["review"]}}}}}
+```
+
+If the assignment was edited, claimed, or prepared after the read, the update
+returns a conflict. Re-read before deciding whether the new state should be
+changed. Breaking (alpha): `assignments.update` now uses this nested
+compare-and-set shape and no longer changes lifecycle or execution fields.
+
 ### 5. Let A Compatible Agent Find Work
 
 An agent can ask for queued assignments matching its kind and skills:
@@ -144,10 +159,20 @@ host does not need a side channel to recover promoted project memory. Skill
 metadata and source locators are provenance hints; Cairnline does not inject
 `SKILL.md` bodies or fetch source locators.
 
+After claiming, a host may attach its execution reference or generated context
+snapshot without marking work as started:
+
+```json
+{"jsonrpc":"2.0","id":8,"method":"tools/call","params":{"name":"assignments.prepare","arguments":{"project_id":"PROJECT_ID","assignment_id":"ASSIGNMENT_ID","claimed_by":"local-agent-reviewer","execution_ref":{"kind":"task_run","run_id":"local-run-1"},"context_snapshot_id":"HOST_CONTEXT_SNAPSHOT_ID"}}}
+```
+
+Preparation returns a conflict if the assignment is no longer claimed by that
+exact worker.
+
 ### 8. Mark It Running
 
 ```json
-{"jsonrpc":"2.0","id":8,"method":"tools/call","params":{"name":"assignments.update_status","arguments":{"project_id":"PROJECT_ID","assignment_id":"ASSIGNMENT_ID","status":"running","execution_ref":{"kind":"task_run","run_id":"local-run-1"}}}}
+{"jsonrpc":"2.0","id":9,"method":"tools/call","params":{"name":"assignments.update_status","arguments":{"project_id":"PROJECT_ID","assignment_id":"ASSIGNMENT_ID","status":"running","execution_ref":{"kind":"task_run","run_id":"local-run-1"}}}}
 ```
 
 `execution_ref` is a structured, host-neutral reference to the execution the
@@ -171,7 +196,7 @@ authoritative data.
 When the host pauses the execution on a human approval gate, report it:
 
 ```json
-{"jsonrpc":"2.0","id":8,"method":"tools/call","params":{"name":"assignments.update_status","arguments":{"project_id":"PROJECT_ID","assignment_id":"ASSIGNMENT_ID","status":"awaiting_approval","execution_ref":{"kind":"task_run","run_id":"local-run-1","pending_approvals":1}}}}
+{"jsonrpc":"2.0","id":10,"method":"tools/call","params":{"name":"assignments.update_status","arguments":{"project_id":"PROJECT_ID","assignment_id":"ASSIGNMENT_ID","status":"awaiting_approval","execution_ref":{"kind":"task_run","run_id":"local-run-1","pending_approvals":1}}}}
 ```
 
 `awaiting_approval` is a first-class assignment status so portable readers can
@@ -182,7 +207,7 @@ resolves. The approval object itself stays host-owned.
 ### 9. Record Evidence
 
 ```json
-{"jsonrpc":"2.0","id":9,"method":"tools/call","params":{"name":"evidence.record","arguments":{"project_id":"PROJECT_ID","work_item_id":"WORK_ITEM_ID","assignment_id":"ASSIGNMENT_ID","title":"Checklist review notes","body":"Reviewed the launch checklist and found two missing owner approvals.","locator":"notes://launch-checklist-review","source_kind":"note","external_id":"launch-review-1","provider":"local","trust_label":"agent_reported"}}}
+{"jsonrpc":"2.0","id":11,"method":"tools/call","params":{"name":"evidence.record","arguments":{"project_id":"PROJECT_ID","work_item_id":"WORK_ITEM_ID","assignment_id":"ASSIGNMENT_ID","title":"Checklist review notes","body":"Reviewed the launch checklist and found two missing owner approvals.","locator":"notes://launch-checklist-review","source_kind":"note","external_id":"launch-review-1","provider":"local","trust_label":"agent_reported"}}}
 ```
 
 Evidence locators are stored as metadata. Clients must validate schemes before
@@ -191,7 +216,7 @@ rendering locators as links or opening them.
 ### 10. Complete The Assignment
 
 ```json
-{"jsonrpc":"2.0","id":10,"method":"tools/call","params":{"name":"assignments.complete","arguments":{"project_id":"PROJECT_ID","assignment_id":"ASSIGNMENT_ID","status":"completed","execution_ref":{"kind":"task_run","run_id":"local-run-1"}}}}
+{"jsonrpc":"2.0","id":12,"method":"tools/call","params":{"name":"assignments.complete","arguments":{"project_id":"PROJECT_ID","assignment_id":"ASSIGNMENT_ID","status":"completed","execution_ref":{"kind":"task_run","run_id":"local-run-1"}}}}
 ```
 
 Use `status:"failed"` when the agent cannot complete the work. The work item
@@ -200,7 +225,7 @@ remains durable coordination state for an operator or another agent to inspect.
 ### 11. Inspect Closeout Readiness
 
 ```json
-{"jsonrpc":"2.0","id":11,"method":"tools/call","params":{"name":"work_items.closeout_readiness","arguments":{"project_id":"PROJECT_ID","work_item_id":"WORK_ITEM_ID"}}}
+{"jsonrpc":"2.0","id":13,"method":"tools/call","params":{"name":"work_items.closeout_readiness","arguments":{"project_id":"PROJECT_ID","work_item_id":"WORK_ITEM_ID"}}}
 ```
 
 Closeout readiness is advisory. Cairnline tells the operator whether assignments,
@@ -213,13 +238,13 @@ Cairnline also exposes read-only resources for clients that prefer resource
 pickers over tool calls. Discover parameterized URI shapes:
 
 ```json
-{"jsonrpc":"2.0","id":12,"method":"resources/templates/list"}
+{"jsonrpc":"2.0","id":14,"method":"resources/templates/list"}
 ```
 
 Then read concrete resources such as the assignment launch packet:
 
 ```json
-{"jsonrpc":"2.0","id":13,"method":"resources/read","params":{"uri":"cairnline://projects/PROJECT_ID/assignments/ASSIGNMENT_ID/launch-packet"}}
+{"jsonrpc":"2.0","id":15,"method":"resources/read","params":{"uri":"cairnline://projects/PROJECT_ID/assignments/ASSIGNMENT_ID/launch-packet"}}
 ```
 
 ## Tool Error Shape

internal/app/tools.go

@@ -5,6 +5,7 @@ import (
 	"encoding/json"
 	"fmt"
 	"strings"
+	"time"
 
 	"github.com/hecatehq/cairnline/internal/core"
 	"github.com/hecatehq/cairnline/internal/mcp"
@@ -682,34 +683,50 @@ func RegisterTools(server *mcp.Server, service *core.Service, version string) {
 
 	server.RegisterTool(mcp.Tool{
 		Name:        "assignments.update",
-		Title:       "Update assignment metadata",
-		Description: "Update assignment coordination metadata such as work item, role, root, execution mode, desired agent, status, and context refs.",
+		Title:       "Update queued assignment metadata",
+		Description: "Compare and replace coordination metadata on a pristine queued assignment. Returns a conflict if the assignment changed or was claimed after it was read.",
 		InputSchema: json.RawMessage(`{
 			"type":"object",
 			"properties":{
 				"project_id":{"type":"string","minLength":1},
 				"assignment_id":{"type":"string","minLength":1},
-				"work_item_id":{"type":"string","minLength":1},
-				"role_id":{"type":"string","minLength":1},
-				"root_id":{"type":"string"},
-				"execution_mode":{"type":"string","enum":["manual","mcp_pull","external_adapter","orchestrated"]},
-				"desired_agent_kind":{"type":"string"},
-				"skill_ids":{"type":"array","items":{"type":"string"}},
-				"status":{"type":"string","enum":["queued","claimed","running","awaiting_approval","awaiting_review","completed","failed","cancelled"]},
-				"execution_ref":{
+				"expected":{
 					"type":"object",
 					"properties":{
-						"kind":{"type":"string"},
-						"task_id":{"type":"string"},
-						"run_id":{"type":"string"},
-						"session_id":{"type":"string"},
-						"trace_id":{"type":"string"},
-						"pending_approvals":{"type":"integer","minimum":0}
-					}
+						"work_item_id":{"type":"string","minLength":1},
+						"role_id":{"type":"string","minLength":1},
+						"root_id":{"type":"string"},
+						"execution_mode":{"type":"string","enum":["manual","mcp_pull","external_adapter","orchestrated"]},
+						"desired_agent":{
+							"type":"object",
+							"properties":{
+								"kind":{"type":"string"},
+								"skill_ids":{"type":"array","items":{"type":"string"}}
+							}
+						}
+					},
+					"required":["work_item_id","role_id","execution_mode"]
 				},
-				"context_snapshot_id":{"type":"string"}
+				"expected_updated_at":{"type":"string","format":"date-time"},
+				"replacement":{
+					"type":"object",
+					"properties":{
+						"work_item_id":{"type":"string","minLength":1},
+						"role_id":{"type":"string","minLength":1},
+						"root_id":{"type":"string"},
+						"execution_mode":{"type":"string","enum":["manual","mcp_pull","external_adapter","orchestrated"]},
+						"desired_agent":{
+							"type":"object",
+							"properties":{
+								"kind":{"type":"string"},
+								"skill_ids":{"type":"array","items":{"type":"string"}}
+							}
+						}
+					},
+					"required":["work_item_id","role_id","execution_mode"]
+				}
 			},
-			"required":["project_id","assignment_id","work_item_id","role_id"]
+			"required":["project_id","assignment_id","expected","expected_updated_at","replacement"]
 		}`),
 	}, updateAssignment(service))
 
@@ -728,6 +745,37 @@ func RegisterTools(server *mcp.Server, service *core.Service, version string) {
 		}`),
 	}, claimAssignment(service))
 
+	server.RegisterTool(mcp.Tool{
+		Name:        "assignments.prepare",
+		Title:       "Prepare claimed assignment",
+		Description: "Attach host execution or context references while the assignment is still claimed by the expected worker. This does not mark work as started.",
+		InputSchema: json.RawMessage(`{
+			"type":"object",
+			"properties":{
+				"project_id":{"type":"string","minLength":1},
+				"assignment_id":{"type":"string","minLength":1},
+				"claimed_by":{"type":"string","minLength":1},
+				"execution_ref":{
+					"type":"object",
+					"properties":{
+						"kind":{"type":"string"},
+						"task_id":{"type":"string"},
+						"run_id":{"type":"string"},
+						"session_id":{"type":"string"},
+						"trace_id":{"type":"string"},
+						"pending_approvals":{"type":"integer","minimum":0}
+					}
+				},
+				"context_snapshot_id":{"type":"string","minLength":1}
+			},
+			"required":["project_id","assignment_id","claimed_by"],
+			"anyOf":[
+				{"required":["execution_ref"]},
+				{"required":["context_snapshot_id"]}
+			]
+		}`),
+	}, prepareAssignment(service))
+
 	server.RegisterTool(mcp.Tool{
 		Name:        "assignments.release",
 		Title:       "Release assignment claim",
@@ -1338,6 +1386,7 @@ func coordinationCapabilities(version string) mcp.ToolHandler {
 				core.AssignmentQueued,
 				core.AssignmentClaimed,
 				core.AssignmentRunning,
+				core.AssignmentAwaitingApproval,
 				core.AssignmentReview,
 				core.AssignmentCompleted,
 				core.AssignmentFailed,
@@ -2635,37 +2684,21 @@ func createAssignment(service *core.Service) mcp.ToolHandler {
 
 func updateAssignment(service *core.Service) mcp.ToolHandler {
 	type args struct {
-		ProjectID         string            `json:"project_id"`
-		AssignmentID      string            `json:"assignment_id"`
-		WorkItemID        string            `json:"work_item_id"`
-		RoleID            string            `json:"role_id"`
-		RootID            string            `json:"root_id"`
-		ExecutionMode     string            `json:"execution_mode"`
-		DesiredAgentKind  string            `json:"desired_agent_kind"`
-		SkillIDs          []string          `json:"skill_ids"`
-		Status            string            `json:"status"`
-		ExecutionRef      core.ExecutionRef `json:"execution_ref"`
-		ContextSnapshotID string            `json:"context_snapshot_id"`
+		ProjectID         string                      `json:"project_id"`
+		AssignmentID      string                      `json:"assignment_id"`
+		Expected          core.AssignmentCoordination `json:"expected"`
+		ExpectedUpdatedAt time.Time                   `json:"expected_updated_at"`
+		Replacement       core.AssignmentCoordination `json:"replacement"`
 	}
 	return func(ctx context.Context, raw json.RawMessage) (mcp.CallToolResult, error) {
 		var input args
 		if err := json.Unmarshal(raw, &input); err != nil {
 			return mcp.CallToolResult{}, invalidArguments(err)
 		}
-		item, err := service.UpdateAssignment(ctx, core.Assignment{
-			ProjectID:     input.ProjectID,
-			ID:            input.AssignmentID,
-			WorkItemID:    input.WorkItemID,
-			RoleID:        input.RoleID,
-			RootID:        input.RootID,
-			ExecutionMode: input.ExecutionMode,
-			Status:        input.Status,
-			DesiredAgent: core.DesiredAgent{
-				Kind:     input.DesiredAgentKind,
-				SkillIDs: input.SkillIDs,
-			},
-			ExecutionRef:      input.ExecutionRef,
-			ContextSnapshotID: input.ContextSnapshotID,
+		item, err := service.UpdateQueuedAssignment(ctx, input.ProjectID, input.AssignmentID, core.QueuedAssignmentUpdate{
+			Expected:          input.Expected,
+			ExpectedUpdatedAt: input.ExpectedUpdatedAt,
+			Replacement:       input.Replacement,
 		})
 		if err != nil {
 			return mcp.CallToolResult{}, err
@@ -2705,6 +2738,34 @@ func claimAssignment(service *core.Service) mcp.ToolHandler {
 	}
 }
 
+func prepareAssignment(service *core.Service) mcp.ToolHandler {
+	type args struct {
+		ProjectID         string            `json:"project_id"`
+		AssignmentID      string            `json:"assignment_id"`
+		ClaimedBy         string            `json:"claimed_by"`
+		ExecutionRef      core.ExecutionRef `json:"execution_ref"`
+		ContextSnapshotID string            `json:"context_snapshot_id"`
+	}
+	return func(ctx context.Context, raw json.RawMessage) (mcp.CallToolResult, error) {
+		var input args
+		if err := json.Unmarshal(raw, &input); err != nil {
+			return mcp.CallToolResult{}, invalidArguments(err)
+		}
+		item, err := service.PrepareAssignment(ctx, input.ProjectID, input.AssignmentID, core.AssignmentPreparation{
+			ClaimedBy:         input.ClaimedBy,
+			ExecutionRef:      input.ExecutionRef,
+			ContextSnapshotID: input.ContextSnapshotID,
+		})
+		if err != nil {
+			return mcp.CallToolResult{}, err
+		}
+		return mcp.CallToolResult{
+			Content:           mcp.TextContent(fmt.Sprintf("Prepared assignment %s", item.ID)),
+			StructuredContent: item,
+		}, nil
+	}
+}
+
 func releaseAssignment(service *core.Service) mcp.ToolHandler {
 	type args struct {
 		ProjectID    string `json:"project_id"`