agentic-mobile-control/openspec/changes/task-cancellation/specs/task-scheduler/spec.md

MODIFIED Requirements

Requirement: Terminal transitions validate the active lease

The system SHALL accept a done, failed, or cancelled result only from the current active task attempt and lease and SHALL make repeated identical terminal reports idempotent.

Scenario: Active lease reports completion

• WHEN the active lease owner reports a terminal result
• THEN the task transitions once to done, failed, or cancelled and releases its device reservation

Scenario: Superseded lease reports completion

• WHEN a result references a lease superseded by expiry and retry
• THEN the result is rejected and cannot overwrite the current task attempt

Requirement: Expired attempts follow bounded retry policy

The system SHALL detect expired assigned or dispatched leases and SHALL either requeue the task with its reservation released, mark it failed when the configured attempt limit is reached, or mark it cancelled when a cancellation request is pending against it.

Scenario: Lease expires with attempts remaining

• WHEN an active lease expires before a terminal result and the task has remaining attempts and no pending cancellation request
• THEN the task returns to queued, the previous device reservation is released, and the expired attempt remains auditable

Scenario: Lease expires at attempt limit

• WHEN an active lease expires and the task has reached its maximum attempts
• THEN the task becomes failed with a lease-expiry reason and its device reservation is released

Scenario: Lease expires with a cancellation pending

• WHEN an active lease expires on a task that has a pending cancellation request, regardless of remaining attempts
• THEN the task becomes cancelled rather than being requeued or marked failed, and its device reservation is released

ADDED Requirements

Requirement: Task status includes a reachable cancelled value

The ScheduledTaskStatus SHALL include cancelled as a terminal status reachable from queued, assigned, or dispatched, alongside the existing done and failed terminal statuses.

Scenario: Cancelled status is a valid terminal state

• WHEN a task's cancellation completes, whether immediately from queued or after collaborative stop from assigned/dispatched
• THEN the task's status is cancelled, and no further assignment, claim, or lease-renewal operation is accepted against it

Requirement: Cancellation requests are recorded durably against in-flight tasks

The scheduler repository SHALL persist a cancellation request against an assigned or dispatched task's current attempt such that the request is observable across a control-plane process restart, before the task reaches a terminal status.

Scenario: Cancellation request survives a restart

• WHEN a cancellation request is recorded against a dispatched task and the control plane process restarts before the Host next renews its lease
• THEN the pending cancellation request is still present and is surfaced to the Host on its next renewal after restart

Requirement: Lease renewal surfaces a pending cancellation request

The scheduler repository's lease-renewal operation SHALL report whether the renewing attempt has a pending cancellation request, without altering the normal lease-extension outcome.

Scenario: Renewal on a task with a pending cancellation

• WHEN the owning host renews the lease for an attempt that has a pending cancellation request
• THEN the lease is extended normally and the renewal result additionally indicates the pending cancellation

Scenario: Renewal on a task without a pending cancellation

• WHEN the owning host renews the lease for an attempt with no pending cancellation request
• THEN the lease is extended normally and the renewal result indicates no pending cancellation