Add agent lease fencing contract

contracts/work/lease.go

@@ -0,0 +1,22 @@
+package work
+
+import "time"
+
+type AgentLeaseID string
+type AgentFencingToken uint64
+type AgentLeaseState string
+
+const (
+	AgentLeaseActive  AgentLeaseState = "ACTIVE"
+	AgentLeaseExpired AgentLeaseState = "EXPIRED"
+)
+
+type AgentLease struct {
+	ID           AgentLeaseID
+	RunID        AgentRunID
+	WorkerID     string
+	FencingToken AgentFencingToken
+	State        AgentLeaseState
+	AcquiredAt   time.Time
+	ExpiresAt    time.Time
+}

dev/ACTIVE_TASK.json

@@ -1,5 +1,5 @@
 {
-  "task_file": "dev/tasks/DEV-000115-cognitive-admission-control.json",
-  "task_id": "DEV-000115",
+  "task_file": "dev/tasks/DEV-000116-agent-lease-fencing.json",
+  "task_id": "DEV-000116",
   "task_revision": 1
 }

dev/tasks/DEV-000116-agent-lease-fencing.json

@@ -0,0 +1,23 @@
+{
+  "task_id": "DEV-000116",
+  "task_revision": 1,
+  "architecture_revision": "ADR-0018",
+  "base_repo_revision": "cb92f95",
+  "risk_tier": "E",
+  "intent": "Add typed durable-agent lease and fencing-token transitions for worker start/heartbeat without implementing a dispatcher or persistence adapter.",
+  "requirement_ids": ["WP-301", "Worker lease confirms actual start", "Heartbeat fencing"],
+  "allowed_change_scope": {"modules": ["work-agent-execution"], "paths": ["contracts/work/**", "modules/work/domain/**", "tests/agent_execution/**", "dev/ACTIVE_TASK.json", "dev/tasks/DEV-000116-agent-lease-fencing.json"]},
+  "forbidden_change_scope": {"paths": ["architecture/**", "database/**", "migrations/**", "deploy/**", "security/**", "cmd/**", "runtime/**", "adapters/**", ".gitea/**"]},
+  "allowed_architecture_delta": {"new_cross_module_dependencies": 0, "new_canonical_owners": 0, "new_privileges": 0, "new_third_party_dependencies": 0, "new_database_owner_roles": 0},
+  "contracts": {"consume": ["ADR-0017 delegation/run ownership", "Proposed ADR-0020 Agent Execution Plane", "Existing Work AgentRun identity"], "may_change": ["Work agent lease/fencing contract"]},
+  "semantic_owner": "work-agent-execution",
+  "canonical_state": [],
+  "state_transitions": ["dispatch -> lease acquired -> heartbeat renewed", "wrong worker/token/expired lease -> rejected callback"],
+  "side_effects_and_privileges": ["Pure transition helper; no queue, persistence, worker process, credential access or external mutation"],
+  "persistence_and_migrations": ["No schema or migration changes"],
+  "failure_retry_restart": ["Fencing token changes on a new lease; late old-token heartbeat is rejected"],
+  "assumptions": ["A durable repository will persist the lease atomically later", "Lease acquisition is separate from process-local execution", "Worker identity is authenticated by a later adapter boundary"],
+  "acceptance_scenarios": ["Valid worker acquires lease", "Matching worker renews before expiry", "Wrong worker/token rejected", "Expired lease cannot renew", "New token fences old run"],
+  "required_tests": ["go test ./...", "go vet ./...", "go run ./cmd/devctl preflight -active dev/ACTIVE_TASK.json", "go run ./cmd/devctl check-diff -active dev/ACTIVE_TASK.json", "go run ./cmd/devctl check-architecture", "go run ./cmd/devctl/independent", "git diff --check", "agent lease tests"],
+  "terminal_gap_states": ["BLOCKED_BY_MISSING_CAPABILITY", "BLOCKED_BY_SPEC_GAP", "BLOCKED_BY_CONFLICT"]
+}

modules/work/domain/lease.go

@@ -0,0 +1,25 @@
+package domain
+
+import (
+	"errors"
+	"time"
+
+	"git.cin.su/m/Assistant/contracts/work"
+)
+
+var ErrLeaseRejected = errors.New("agent lease rejected")
+
+func AcquireAgentLease(runID work.AgentRunID, workerID string, token work.AgentFencingToken, now time.Time, ttl time.Duration) (work.AgentLease, error) {
+	if runID == "" || workerID == "" || token == 0 || now.IsZero() || ttl <= 0 {
+		return work.AgentLease{}, ErrLeaseRejected
+	}
+	return work.AgentLease{ID: work.AgentLeaseID(string(runID) + ":" + workerID), RunID: runID, WorkerID: workerID, FencingToken: token, State: work.AgentLeaseActive, AcquiredAt: now, ExpiresAt: now.Add(ttl)}, nil
+}
+
+func RenewAgentLease(lease work.AgentLease, workerID string, token work.AgentFencingToken, now time.Time, ttl time.Duration) (work.AgentLease, error) {
+	if lease.State != work.AgentLeaseActive || lease.WorkerID != workerID || lease.FencingToken != token || now.IsZero() || !now.Before(lease.ExpiresAt) || ttl <= 0 {
+		return work.AgentLease{}, ErrLeaseRejected
+	}
+	lease.ExpiresAt = now.Add(ttl)
+	return lease, nil
+}

tests/agent_execution/lease_test.go

@@ -0,0 +1,34 @@
+package agent_execution_test
+
+import (
+	"testing"
+	"time"
+
+	"git.cin.su/m/Assistant/contracts/work"
+	workdomain "git.cin.su/m/Assistant/modules/work/domain"
+)
+
+func TestAgentLeaseFencesWorkerAndToken(t *testing.T) {
+	now := time.Unix(100, 0)
+	lease, err := workdomain.AcquireAgentLease("run-1", "worker-a", 7, now, time.Minute)
+	if err != nil || lease.State != work.AgentLeaseActive {
+		t.Fatalf("lease = %#v %v", lease, err)
+	}
+	if _, err := workdomain.RenewAgentLease(lease, "worker-b", 7, now.Add(time.Second), time.Minute); err == nil {
+		t.Fatal("expected worker fencing")
+	}
+	if _, err := workdomain.RenewAgentLease(lease, "worker-a", 8, now.Add(time.Second), time.Minute); err == nil {
+		t.Fatal("expected token fencing")
+	}
+	if renewed, err := workdomain.RenewAgentLease(lease, "worker-a", 7, now.Add(time.Second), time.Minute); err != nil || !renewed.ExpiresAt.After(lease.ExpiresAt) {
+		t.Fatalf("renewed = %#v %v", renewed, err)
+	}
+}
+
+func TestExpiredLeaseCannotRenew(t *testing.T) {
+	now := time.Unix(100, 0)
+	lease, _ := workdomain.AcquireAgentLease("run-1", "worker-a", 1, now, time.Second)
+	if _, err := workdomain.RenewAgentLease(lease, "worker-a", 1, now.Add(time.Second), time.Second); err == nil {
+		t.Fatal("expected expired lease rejection")
+	}
+}